diff options
Diffstat (limited to 'contrib/gcc/gcc.texi')
| -rw-r--r-- | contrib/gcc/gcc.texi | 4722 |
1 files changed, 4722 insertions, 0 deletions
diff --git a/contrib/gcc/gcc.texi b/contrib/gcc/gcc.texi new file mode 100644 index 0000000..7c6b056 --- /dev/null +++ b/contrib/gcc/gcc.texi @@ -0,0 +1,4722 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename gcc.info +@c @setfilename usegcc.info +@c @setfilename portgcc.info +@c To produce the full manual, use the "gcc.info" setfilename, and +@c make sure the following do NOT begin with '@c' (and the @clear lines DO) +@set INTERNALS +@set USING +@c To produce a user-only manual, use the "usegcc.info" setfilename, and +@c make sure the following does NOT begin with '@c': +@c @clear INTERNALS +@c To produce a porter-only manual, use the "portgcc.info" setfilename, +@c and make sure the following does NOT begin with '@c': +@c @clear USING + +@c i have commented out the smallbook command below, and reformatted +@c this manual in the regular book size for distribution. in addition, +@c i commented out the commands that shift the text to one or the other +@c side of the page for smallbook printing (which makes it easier for +@c the photocopying people to handle...). -mew, 15june93 + +@c (For FSF printing, turn on smallbook, comment out finalout below; +@c that is all that is needed.) + +@c smallbook + +@c i also commented out the finalout command, so if there *are* any +@c overfulls, you'll (hopefully) see the rectangle in the right hand +@c margin. -mew 15june93 +@c finalout + +@c NOTE: checks/things to do: +@c +@c -have bob do a search in all seven files for "mew" (ideally --mew, +@c but i may have forgotten the occasional "--"..). +@c -item/itemx, text after all (sub/sub)section titles, etc.. +@c -consider putting the lists of options on pp 17--> etc in columns or +@c some such. +@c -spellcheck +@c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi +@c -overfulls. do a search for "mew" in the files, and you will see +@c overfulls that i noted but could not deal with. +@c -have to add text: beginning of chapter 8 + +@c +@c anything else? --mew 10feb93 + + + +@ifset INTERNALS +@ifset USING +@settitle Using and Porting GNU CC +@end ifset +@end ifset +@c seems reasonable to assume at least one of INTERNALS or USING is set... +@ifclear INTERNALS +@settitle Using GNU CC +@end ifclear +@ifclear USING +@settitle Porting GNU CC +@end ifclear + +@syncodeindex fn cp +@syncodeindex vr cp +@c %**end of header + +@c Use with @@smallbook. + +@c Cause even numbered pages to be printed on the left hand side of +@c the page and odd numbered pages to be printed on the right hand +@c side of the page. Using this, you can print on both sides of a +@c sheet of paper and have the text on the same part of the sheet. + +@c The text on right hand pages is pushed towards the right hand +@c margin and the text on left hand pages is pushed toward the left +@c hand margin. +@c (To provide the reverse effect, set bindingoffset to -0.75in.) + +@c @tex +@c \global\bindingoffset=0.75in +@c \global\normaloffset =0.75in +@c @end tex + +@ifinfo +@ifset INTERNALS +@ifset USING +This file documents the use and the internals of the GNU compiler. +@end ifset +@end ifset +@ifclear USING +This file documents the internals of the GNU compiler. +@end ifclear +@ifclear INTERNALS +This file documents the use of the GNU compiler. +@end ifclear + +Published by the Free Software Foundation +59 Temple Place - Suite 330 +Boston, MA 02111-1307 USA + +Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``GNU General Public License,'' ``Funding for Free +Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``GNU General Public License,'' +``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look +And Feel'@w{}'', and this permission notice, may be included in +translations approved by the Free Software Foundation instead of in the +original English. +@end ifinfo + +@setchapternewpage odd + +@titlepage +@ifset INTERNALS +@ifset USING +@center @titlefont{Using and Porting GNU CC} + +@end ifset +@end ifset +@ifclear INTERNALS +@title Using GNU CC +@end ifclear +@ifclear USING +@title Porting GNU CC +@end ifclear +@sp 2 +@center Richard M. Stallman +@sp 3 +@center Last updated 26 November 1995 +@sp 1 +@c The version number appears twice more in this file. + +@center for version 2.7.2 +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1988, 89, 92, 93, 94, 1995 Free Software Foundation, Inc. +@sp 2 +For GCC Version 2.7.2@* +@sp 1 +Published by the Free Software Foundation @* +59 Temple Place - Suite 330@* +Boston, MA 02111-1307, USA@* +Last printed November, 1995.@* +Printed copies are available for $50 each.@* +ISBN 1-882114-66-3 +@sp 1 +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``GNU General Public License,'' ``Funding for Free +Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``GNU General Public License,'' +``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look +And Feel'@w{}'', and this permission notice, may be included in +translations approved by the Free Software Foundation instead of in the +original English. +@end titlepage +@page + +@ifinfo + +@node Top, Copying,, (DIR) +@top Introduction +@cindex introduction + +@ifset INTERNALS +@ifset USING +This manual documents how to run, install and port the GNU +compiler, as well as its new features and incompatibilities, and how to +report bugs. It corresponds to GNU CC version 2.7.2. +@end ifset +@end ifset + +@ifclear INTERNALS +This manual documents how to run and install the GNU compiler, +as well as its new features and incompatibilities, and how to report +bugs. It corresponds to GNU CC version 2.7.2. +@end ifclear +@ifclear USING +This manual documents how to port the GNU compiler, +as well as its new features and incompatibilities, and how to report +bugs. It corresponds to GNU CC version 2.7.1. +@end ifclear + +@end ifinfo +@menu +* Copying:: GNU General Public License says + how you can copy and share GNU CC. +* Contributors:: People who have contributed to GNU CC. +* Funding:: How to help assure funding for free software. +* Look and Feel:: Protect your freedom---fight ``look and feel''. +@ifset USING +* G++ and GCC:: You can compile C or C++ programs. +* Invoking GCC:: Command options supported by @samp{gcc}. +* Installation:: How to configure, compile and install GNU CC. +* C Extensions:: GNU extensions to the C language family. +* C++ Extensions:: GNU extensions to the C++ language. +* Trouble:: If you have trouble installing GNU CC. +* Bugs:: How, why and where to report bugs. +* Service:: How to find suppliers of support for GNU CC. +* VMS:: Using GNU CC on VMS. +@end ifset +@ifset INTERNALS +* Portability:: Goals of GNU CC's portability features. +* Interface:: Function-call interface of GNU CC output. +* Passes:: Order of passes, what they do, and what each file is for. +* RTL:: The intermediate representation that most passes work on. +* Machine Desc:: How to write machine description instruction patterns. +* Target Macros:: How to write the machine description C macros. +* Config:: Writing the @file{xm-@var{machine}.h} file. +* Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files. +@end ifset + +* Index:: Index of concepts and symbol names. +@end menu + +@node Copying +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@smallexample +Yoyodyne, Inc., hereby disclaims all copyright interest in the program +`Gnomovision' (which makes passes at compilers) written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end smallexample + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +@node Contributors +@unnumbered Contributors to GNU CC +@cindex contributors + +In addition to Richard Stallman, several people have written parts +of GNU CC. + +@itemize @bullet +@item +The idea of using RTL and some of the optimization ideas came from the +program PO written at the University of Arizona by Jack Davidson and +Christopher Fraser. See ``Register Allocation and Exhaustive Peephole +Optimization'', Software Practice and Experience 14 (9), Sept. 1984, +857-866. + +@item +Paul Rubin wrote most of the preprocessor. + +@item +Leonard Tower wrote parts of the parser, RTL generator, and RTL +definitions, and of the Vax machine description. + +@item +Ted Lemon wrote parts of the RTL reader and printer. + +@item +Jim Wilson implemented loop strength reduction and some other +loop optimizations. + +@item +Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed +the support for the Sony NEWS machine. + +@item +Charles LaBrec contributed the support for the Integrated Solutions +68020 system. + +@item +Michael Tiemann of Cygnus Support wrote the front end for C++, as well +as the support for inline functions and instruction scheduling. Also +the descriptions of the National Semiconductor 32000 series cpu, the +SPARC cpu and part of the Motorola 88000 cpu. + +@item +Gerald Baumgartner added the signature extension to the C++ front-end. + +@item +Jan Stein of the Chalmers Computer Society provided support for +Genix, as well as part of the 32000 machine description. + +@item +Randy Smith finished the Sun FPA support. + +@item +Robert Brown implemented the support for Encore 32000 systems. + +@item +David Kashtan of SRI adapted GNU CC to VMS. + +@item +Alex Crain provided changes for the 3b1. + +@item +Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for +the 9000 series 300. + +@item +William Schelter did most of the work on the Intel 80386 support. + +@item +Christopher Smith did the port for Convex machines. + +@item +Paul Petersen wrote the machine description for the Alliant FX/8. + +@item +Dario Dariol contributed the four varieties of sample programs +that print a copy of their source. + +@item +Alain Lichnewsky ported GNU CC to the Mips cpu. + +@item +Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the Tahoe. + +@item +Jonathan Stone wrote the machine description for the Pyramid computer. + +@item +Gary Miller ported GNU CC to Charles River Data Systems machines. + +@item +Richard Kenner of the New York University Ultracomputer Research +Laboratory wrote the machine descriptions for the AMD 29000, the DEC +Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for +instruction attributes. He also made changes to better support RISC +processors including changes to common subexpression elimination, +strength reduction, function calling sequence handling, and condition +code support, in addition to generalizing the code for frame pointer +elimination. + +@item +Richard Kenner and Michael Tiemann jointly developed reorg.c, the delay +slot scheduler. + +@item +Mike Meissner and Tom Wood of Data General finished the port to the +Motorola 88000. + +@item +Masanobu Yuhara of Fujitsu Laboratories implemented the machine +description for the Tron architecture (specifically, the Gmicro). + +@item +NeXT, Inc.@: donated the front end that supports the Objective C +language. +@c We need to be careful to make it clear that "Objective C" +@c is the name of a language, not that of a program or product. + +@item +James van Artsdalen wrote the code that makes efficient use of +the Intel 80387 register stack. + +@item +Mike Meissner at the Open Software Foundation finished the port to the +MIPS cpu, including adding ECOFF debug support, and worked on the +Intel port for the Intel 80386 cpu. + +@item +Ron Guilmette implemented the @code{protoize} and @code{unprotoize} +tools, the support for Dwarf symbolic debugging information, and much of +the support for System V Release 4. He has also worked heavily on the +Intel 386 and 860 support. + +@item +Torbjorn Granlund implemented multiply- and divide-by-constant +optimization, improved long long support, and improved leaf function +register allocation. + +@item +Mike Stump implemented the support for Elxsi 64 bit CPU. + +@item +John Wehle added the machine description for the Western Electric 32000 +processor used in several 3b series machines (no relation to the +National Semiconductor 32000 processor). + +@ignore @c These features aren't advertised yet, since they don't fully work. +@item +Analog Devices helped implement the support for complex data types +and iterators. +@end ignore + +@item +Holger Teutsch provided the support for the Clipper cpu. + +@item +Kresten Krab Thorup wrote the run time support for the Objective C +language. + +@item +Stephen Moshier contributed the floating point emulator that assists in +cross-compilation and permits support for floating point numbers wider +than 64 bits. + +@item +David Edelsohn contributed the changes to RS/6000 port to make it +support the PowerPC and POWER2 architectures. + +@item +Steve Chamberlain wrote the support for the Hitachi SH processor. + +@item +Peter Schauer wrote the code to allow debugging to work on the Alpha. + +@item +Oliver M. Kellogg of Deutsche Aerospace contributed the port to the +MIL-STD-1750A. + +@item +Michael K. Gschwind contributed the port to the PDP-11. +@end itemize + +@node Funding +@chapter Funding Free Software + +If you want to have more free software a few years from now, it makes +sense for you to help encourage people to contribute funds for its +development. The most effective approach known is to encourage +commercial redistributors to donate. + +Users of free software systems can boost the pace of development by +encouraging for-a-fee distributors to donate part of their selling price +to free software developers---the Free Software Foundation, and others. + +The way to convince distributors to do this is to demand it and expect +it from them. So when you compare distributors, judge them partly by +how much they give to free software development. Show distributors +they must compete to be the one who gives the most. + +To make this approach work, you must insist on numbers that you can +compare, such as, ``We will donate ten dollars to the Frobnitz project +for each disk sold.'' Don't be satisfied with a vague promise, such as +``A portion of the profits are donated,'' since it doesn't give a basis +for comparison. + +Even a precise fraction ``of the profits from this disk'' is not very +meaningful, since creative accounting and unrelated business decisions +can greatly alter what fraction of the sales price counts as profit. +If the price you pay is $50, ten percent of the profit is probably +less than a dollar; it might be a few cents, or nothing at all. + +Some redistributors do development work themselves. This is useful too; +but to keep everyone honest, you need to inquire how much they do, and +what kind. Some kinds of development make much more long-term +difference than others. For example, maintaining a separate version of +a program contributes very little; maintaining the standard version of a +program for the whole community contributes much. Easy new ports +contribute little, since someone else would surely do them; difficult +ports such as adding a new CPU to the GNU C compiler contribute more; +major new features or packages contribute the most. + +By establishing the idea that supporting further development is ``the +proper thing to do'' when distributing free software for a fee, we can +assure a steady flow of resources into making more free software. + +@display +Copyright (C) 1994 Free Software Foundation, Inc. +Verbatim copying and redistribution of this section is permitted +without royalty; alteration is not permitted. +@end display + +@node Look and Feel +@chapter Protect Your Freedom---Fight ``Look And Feel'' +@c the above chapter heading overflows onto the next line. --mew 1/26/93 + +@quotation +@i{This section is a political message from the League for Programming +Freedom to the users of GNU CC. We have included it here because the +issue of interface copyright is important to the GNU project.} +@end quotation + +Apple, Lotus, and now CDC have tried to create a new form of legal +monopoly: a copyright on a user interface. + +An interface is a kind of language---a set of conventions for +communication between two entities, human or machine. Until a few years +ago, the law seemed clear: interfaces were outside the domain of +copyright, so programmers could program freely and implement whatever +interface the users demanded. Imitating de-facto standard interfaces, +sometimes with improvements, was standard practice in the computer +field. These improvements, if accepted by the users, caught on and +became the norm; in this way, much progress took place. + +Computer users, and most software developers, were happy with this state +of affairs. However, large companies such as Apple and Lotus would +prefer a different system---one in which they can own interfaces and +thereby rid themselves of all serious competitors. They hope that +interface copyright will give them, in effect, monopolies on major +classes of software. + +Other large companies such as IBM and Digital also favor interface +monopolies, for the same reason: if languages become property, they +expect to own many de-facto standard languages. But Apple and Lotus are +the ones who have actually sued. Apple's lawsuit was defeated, for +reasons only partly related to the general issue of interface copyright. + +Lotus won lawsuits against two small companies, which were thus put out +of business. Then they sued Borland; they won in the trial court (no +surprise, since it was the same court that had ruled for Lotus twice +before), but the decision was reversed by the court of appeals, with +help from the League for Programming Freedom in the form of a +friend-of-the-court brief. We are now waiting to see if the Supreme +Court will hear the case. If it does, the League for Programming +Freedom will again submit a brief. + +The battle is not over. Just this summer a company that produced a +simulator for a CDC computer was shut down by a copyright lawsuit by +CDC, which charged that the simulator infringed the copyright on the +manuals for the computer. + +If the monopolists get their way, they will hobble the software field: + +@itemize @bullet +@item +Gratuitous incompatibilities will burden users. Imagine if each car +manufacturer had to design a different way to start, stop, and steer a +car. + +@item +Users will be ``locked in'' to whichever interface they learn; then they +will be prisoners of one supplier, who will charge a monopolistic price. + +@item +Large companies have an unfair advantage wherever lawsuits become +commonplace. Since they can afford to sue, they can intimidate smaller +developers with threats even when they don't really have a case. + +@item +Interface improvements will come slower, since incremental evolution +through creative partial imitation will no longer occur. +@end itemize + +If interface monopolies are accepted, other large companies are waiting +to grab theirs: + +@itemize @bullet +@item +Adobe is expected to claim a monopoly on the interfaces of various +popular application programs, if Lotus ultimately wins the case against +Borland. + +@item +Open Computing magazine reported a Microsoft vice president as threatening +to sue people who imitate the interface of Windows. +@end itemize + +Users invest a great deal of time and money in learning to use computer +interfaces. Far more, in fact, than software developers invest in +developing @emph{and even implementing} the interfaces. Whoever can own +an interface, has made its users into captives, and misappropriated +their investment. + +To protect our freedom from monopolies like these, a group of +programmers and users have formed a grass-roots political organization, +the League for Programming Freedom. + +The purpose of the League is to oppose monopolistic practices such as +interface copyright and software patents. The League calls for a return +to the legal policies of the recent past, in which programmers could +program freely. The League is not concerned with free software as an +issue, and is not affiliated with the Free Software Foundation. + +The League's activities include publicizing the issues, as is being done +here, and filing friend-of-the-court briefs on behalf of defendants sued +by monopolists. + +The League's membership rolls include Donald Knuth, the foremost +authority on algorithms, John McCarthy, inventor of Lisp, Marvin Minsky, +founder of the MIT Artificial Intelligence lab, Guy L. Steele, Jr., +author of well-known books on Lisp and C, as well as Richard Stallman, +the developer of GNU CC. Please join and add your name to the list. +Membership dues in the League are $42 per year for programmers, managers +and professionals; $10.50 for students; $21 for others. + +Activist members are especially important, but members who have no time +to give are also important. Surveys at major ACM conferences have +indicated a vast majority of attendees agree with the League on both +issues (interface copyrights and software patents). If just ten percent +of the programmers who agree with the League join the League, we will +probably triumph. + +To join, or for more information, phone (617) 243-4091 or write to: + +@display +League for Programming Freedom +1 Kendall Square #143 +P.O. Box 9171 +Cambridge, MA 02139 +@end display + +You can also send electronic mail to @code{lpf@@uunet.uu.net}. + +In addition to joining the League, here are some suggestions from the +League for other things you can do to protect your freedom to write +programs: + +@itemize @bullet +@item +Tell your friends and colleagues about this issue and how it threatens +to ruin the computer industry. + +@item +Mention that you are a League member in your @file{.signature}, and +mention the League's email address for inquiries. + +@item +Ask the companies you consider working for or working with to make +statements against software monopolies, and give preference to those +that do. + +@item +When employers ask you to sign contracts giving them copyright on your +work, insist on a clause saying they will not claim the copyright covers +imitating the interface. + +@item +When employers ask you to sign contracts giving them patent rights, +insist on clauses saying they can use these rights only defensively. +Don't rely on ``company policy,'' since that can change at any time; +don't rely on an individual executive's private word, since that person +may be replaced. Get a commitment just as binding as the commitment +they get from you. + +@item +Write to Congress to explain the importance of these issues. + +@display +House Subcommittee on Intellectual Property +2137 Rayburn Bldg +Washington, DC 20515 + +Senate Subcommittee on Patents, Trademarks and Copyrights +United States Senate +Washington, DC 20510 +@end display + +(These committees have received lots of mail already; let's give them +even more.) +@end itemize + +Democracy means nothing if you don't use it. Stand up and be counted! +@ifset USING +@node G++ and GCC +@chapter Compile C, C++, or Objective C + +@cindex Objective C +The C, C++, and Objective C versions of the compiler are integrated; the +GNU C compiler can compile programs written in C, C++, or Objective C. + +@cindex GCC +``GCC'' is a common shorthand term for the GNU C compiler. This is both +the most general name for the compiler, and the name used when the +emphasis is on compiling C programs. + +@cindex C++ +@cindex G++ +When referring to C++ compilation, it is usual to call the compiler +``G++''. Since there is only one compiler, it is also accurate to call +it ``GCC'' no matter what the language context; however, the term +``G++'' is more useful when the emphasis is on compiling C++ programs. + +We use the name ``GNU CC'' to refer to the compilation system as a +whole, and more specifically to the language-independent part of the +compiler. For example, we refer to the optimization options as +affecting the behavior of ``GNU CC'' or sometimes just ``the compiler''. + +Front ends for other languages, such as Ada 9X, Fortran, Modula-3, and +Pascal, are under development. These front-ends, like that for C++, are +built in subdirectories of GNU CC and link to it. The result is an +integrated compiler that can compile programs written in C, C++, +Objective C, or any of the languages for which you have installed front +ends. + +In this manual, we only discuss the options for the C, Objective-C, and +C++ compilers and those of the GNU CC core. Consult the documentation +of the other front ends for the options to use when compiling programs +written in other languages. + +@cindex compiler compared to C++ preprocessor +@cindex intermediate C version, nonexistent +@cindex C intermediate output, nonexistent +G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object +code directly from your C++ program source. There is no intermediate C +version of the program. (By contrast, for example, some other +implementations use a program that generates a C program from your C++ +source.) Avoiding an intermediate C representation of the program means +that you get better object code, and better debugging information. The +GNU debugger, GDB, works with this information in the object code to +give you comprehensive C++ source-level editing capabilities +(@pxref{C,,C and C++,gdb.info, Debugging with GDB}). + +@c FIXME! Someone who knows something about Objective C ought to put in +@c a paragraph or two about it here, and move the index entry down when +@c there is more to point to than the general mention in the 1st par. + +@include invoke.texi + +@include install.texi + +@include extend.texi + +@node Trouble +@chapter Known Causes of Trouble with GNU CC +@cindex bugs, known +@cindex installation trouble +@cindex known causes of trouble + +This section describes known problems that affect users of GNU CC. Most +of these are not GNU CC bugs per se---if they were, we would fix them. +But the result for a user may be like the result of a bug. + +Some of these problems are due to bugs in other software, some are +missing features that are too much work to add, and some are places +where people's opinions differ as to what is best. + +@menu +* Actual Bugs:: Bugs we will fix later. +* Installation Problems:: Problems that manifest when you install GNU CC. +* Cross-Compiler Problems:: Common problems of cross compiling with GNU CC. +* Interoperation:: Problems using GNU CC with other compilers, + and with certain linkers, assemblers and debuggers. +* External Bugs:: Problems compiling certain programs. +* Incompatibilities:: GNU CC is incompatible with traditional C. +* Fixed Headers:: GNU C uses corrected versions of system header files. + This is necessary, but doesn't always work smoothly. +* Standard Libraries:: GNU C uses the system C library, which might not be + compliant with the ISO/ANSI C standard. +* Disappointments:: Regrettable things we can't change, but not quite bugs. +* C++ Misunderstandings:: Common misunderstandings with GNU C++. +* Protoize Caveats:: Things to watch out for when using @code{protoize}. +* Non-bugs:: Things we think are right, but some others disagree. +* Warnings and Errors:: Which problems in your code get warnings, + and which get errors. +@end menu + +@node Actual Bugs +@section Actual Bugs We Haven't Fixed Yet + +@itemize @bullet +@item +The @code{fixincludes} script interacts badly with automounters; if the +directory of system header files is automounted, it tends to be +unmounted while @code{fixincludes} is running. This would seem to be a +bug in the automounter. We don't know any good way to work around it. + +@item +The @code{fixproto} script will sometimes add prototypes for the +@code{sigsetjmp} and @code{siglongjmp} functions that reference the +@code{jmp_buf} type before that type is defined. To work around this, +edit the offending file and place the typedef in front of the +prototypes. + +@item +There are several obscure case of mis-using struct, union, and +enum tags that are not detected as errors by the compiler. + +@item +When @samp{-pedantic-errors} is specified, GNU C will incorrectly give +an error message when a function name is specified in an expression +involving the comma operator. + +@item +Loop unrolling doesn't work properly for certain C++ programs. This is +a bug in the C++ front end. It sometimes emits incorrect debug info, and +the loop unrolling code is unable to recover from this error. +@end itemize + +@node Installation Problems +@section Installation Problems + +This is a list of problems (and some apparent problems which don't +really mean anything is wrong) that show up during installation of GNU +CC. + +@itemize @bullet +@item +On certain systems, defining certain environment variables such as +@code{CC} can interfere with the functioning of @code{make}. + +@item +If you encounter seemingly strange errors when trying to build the +compiler in a directory other than the source directory, it could be +because you have previously configured the compiler in the source +directory. Make sure you have done all the necessary preparations. +@xref{Other Dir}. + +@item +If you build GNU CC on a BSD system using a directory stored in a System +V file system, problems may occur in running @code{fixincludes} if the +System V file system doesn't support symbolic links. These problems +result in a failure to fix the declaration of @code{size_t} in +@file{sys/types.h}. If you find that @code{size_t} is a signed type and +that type mismatches occur, this could be the cause. + +The solution is not to use such a directory for building GNU CC. + +@item +In previous versions of GNU CC, the @code{gcc} driver program looked for +@code{as} and @code{ld} in various places; for example, in files +beginning with @file{/usr/local/lib/gcc-}. GNU CC version 2 looks for +them in the directory +@file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}. + +Thus, to use a version of @code{as} or @code{ld} that is not the system +default, for example @code{gas} or GNU @code{ld}, you must put them in +that directory (or make links to them from that directory). + +@item +Some commands executed when making the compiler may fail (return a +non-zero status) and be ignored by @code{make}. These failures, which +are often due to files that were not found, are expected, and can safely +be ignored. + +@item +It is normal to have warnings in compiling certain files about +unreachable code and about enumeration type clashes. These files' names +begin with @samp{insn-}. Also, @file{real.c} may get some warnings that +you can ignore. + +@item +Sometimes @code{make} recompiles parts of the compiler when installing +the compiler. In one case, this was traced down to a bug in +@code{make}. Either ignore the problem or switch to GNU Make. + +@item +If you have installed a program known as purify, you may find that it +causes errors while linking @code{enquire}, which is part of building +GNU CC. The fix is to get rid of the file @code{real-ld} which purify +installs---so that GNU CC won't try to use it. + +@item +On Linux SLS 1.01, there is a problem with @file{libc.a}: it does not +contain the obstack functions. However, GNU CC assumes that the obstack +functions are in @file{libc.a} when it is the GNU C library. To work +around this problem, change the @code{__GNU_LIBRARY__} conditional +around line 31 to @samp{#if 1}. + +@item +On some 386 systems, building the compiler never finishes because +@code{enquire} hangs due to a hardware problem in the motherboard---it +reports floating point exceptions to the kernel incorrectly. You can +install GNU CC except for @file{float.h} by patching out the command to +run @code{enquire}. You may also be able to fix the problem for real by +getting a replacement motherboard. This problem was observed in +Revision E of the Micronics motherboard, and is fixed in Revision F. +It has also been observed in the MYLEX MXA-33 motherboard. + +If you encounter this problem, you may also want to consider removing +the FPU from the socket during the compilation. Alternatively, if you +are running SCO Unix, you can reboot and force the FPU to be ignored. +To do this, type @samp{hd(40)unix auto ignorefpu}. + +@item +On some 386 systems, GNU CC crashes trying to compile @file{enquire.c}. +This happens on machines that don't have a 387 FPU chip. On 386 +machines, the system kernel is supposed to emulate the 387 when you +don't have one. The crash is due to a bug in the emulator. + +One of these systems is the Unix from Interactive Systems: 386/ix. +On this system, an alternate emulator is provided, and it does work. +To use it, execute this command as super-user: + +@example +ln /etc/emulator.rel1 /etc/emulator +@end example + +@noindent +and then reboot the system. (The default emulator file remains present +under the name @file{emulator.dflt}.) + +Try using @file{/etc/emulator.att}, if you have such a problem on the +SCO system. + +Another system which has this problem is Esix. We don't know whether it +has an alternate emulator that works. + +On NetBSD 0.8, a similar problem manifests itself as these error messages: + +@example +enquire.c: In function `fprop': +enquire.c:2328: floating overflow +@end example + +@item +On SCO systems, when compiling GNU CC with the system's compiler, +do not use @samp{-O}. Some versions of the system's compiler miscompile +GNU CC with @samp{-O}. + +@cindex @code{genflags}, crash on Sun 4 +@item +Sometimes on a Sun 4 you may observe a crash in the program +@code{genflags} or @code{genoutput} while building GNU CC. This is said to +be due to a bug in @code{sh}. You can probably get around it by running +@code{genflags} or @code{genoutput} manually and then retrying the +@code{make}. + +@item +On Solaris 2, executables of GNU CC version 2.0.2 are commonly +available, but they have a bug that shows up when compiling current +versions of GNU CC: undefined symbol errors occur during assembly if you +use @samp{-g}. + +The solution is to compile the current version of GNU CC without +@samp{-g}. That makes a working compiler which you can use to recompile +with @samp{-g}. + +@item +Solaris 2 comes with a number of optional OS packages. Some of these +packages are needed to use GNU CC fully. If you did not install all +optional packages when installing Solaris, you will need to verify that +the packages that GNU CC needs are installed. + +To check whether an optional package is installed, use +the @code{pkginfo} command. To add an optional package, use the +@code{pkgadd} command. For further details, see the Solaris +documentation. + +For Solaris 2.0 and 2.1, GNU CC needs six packages: @samp{SUNWarc}, +@samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and +@samp{SUNWtoo}. + +For Solaris 2.2, GNU CC needs an additional seventh package: @samp{SUNWsprot}. + +@item +On Solaris 2, trying to use the linker and other tools in +@file{/usr/ucb} to install GNU CC has been observed to cause trouble. +For example, the linker may hang indefinitely. The fix is to remove +@file{/usr/ucb} from your @code{PATH}. + +@item +If you use the 1.31 version of the MIPS assembler (such as was shipped +with Ultrix 3.1), you will need to use the -fno-delayed-branch switch +when optimizing floating point code. Otherwise, the assembler will +complain when the GCC compiler fills a branch delay slot with a +floating point instruction, such as @code{add.d}. + +@item +If on a MIPS system you get an error message saying ``does not have gp +sections for all it's [sic] sectons [sic]'', don't worry about it. This +happens whenever you use GAS with the MIPS linker, but there is not +really anything wrong, and it is okay to use the output file. You can +stop such warnings by installing the GNU linker. + +It would be nice to extend GAS to produce the gp tables, but they are +optional, and there should not be a warning about their absence. + +@item +In Ultrix 4.0 on the MIPS machine, @file{stdio.h} does not work with GNU +CC at all unless it has been fixed with @code{fixincludes}. This causes +problems in building GNU CC. Once GNU CC is installed, the problems go +away. + +To work around this problem, when making the stage 1 compiler, specify +this option to Make: + +@example +GCC_FOR_TARGET="./xgcc -B./ -I./include" +@end example + +When making stage 2 and stage 3, specify this option: + +@example +CFLAGS="-g -I./include" +@end example + +@item +Users have reported some problems with version 2.0 of the MIPS +compiler tools that were shipped with Ultrix 4.1. Version 2.10 +which came with Ultrix 4.2 seems to work fine. + +Users have also reported some problems with version 2.20 of the +MIPS compiler tools that were shipped with RISC/os 4.x. The earlier +version 2.11 seems to work fine. + +@item +Some versions of the MIPS linker will issue an assertion failure +when linking code that uses @code{alloca} against shared +libraries on RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug +in the linker, that is supposed to be fixed in future revisions. +To protect against this, GNU CC passes @samp{-non_shared} to the +linker unless you pass an explicit @samp{-shared} or +@samp{-call_shared} switch. + +@item +On System V release 3, you may get this error message +while linking: + +@smallexample +ld fatal: failed to write symbol name @var{something} + in strings table for file @var{whatever} +@end smallexample + +This probably indicates that the disk is full or your ULIMIT won't allow +the file to be as large as it needs to be. + +This problem can also result because the kernel parameter @code{MAXUMEM} +is too small. If so, you must regenerate the kernel and make the value +much larger. The default value is reported to be 1024; a value of 32768 +is said to work. Smaller values may also work. + +@item +On System V, if you get an error like this, + +@example +/usr/local/lib/bison.simple: In function `yyparse': +/usr/local/lib/bison.simple:625: virtual memory exhausted +@end example + +@noindent +that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}. + +@item +Current GNU CC versions probably do not work on version 2 of the NeXT +operating system. + +@item +On NeXTStep 3.0, the Objective C compiler does not work, due, +apparently, to a kernel bug that it happens to trigger. This problem +does not happen on 3.1. + +@item +On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not +allowed to have more than one megabyte of memory. GNU CC cannot compile +itself (or many other programs) with @samp{-O} in that much memory. + +To solve this problem, reconfigure the kernel adding the following line +to the configuration file: + +@smallexample +MAXUMEM = 4096 +@end smallexample + +@item +On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug +in the assembler that must be fixed before GNU CC can be built. This +bug manifests itself during the first stage of compilation, while +building @file{libgcc2.a}: + +@smallexample +_floatdisf +cc1: warning: `-g' option not supported on this version of GCC +cc1: warning: `-g1' option not supported on this version of GCC +./xgcc: Internal compiler error: program as got fatal signal 11 +@end smallexample + +A patched version of the assembler is available by anonymous ftp from +@code{altdorf.ai.mit.edu} as the file +@file{archive/cph/hpux-8.0-assembler}. If you have HP software support, +the patch can also be obtained directly from HP, as described in the +following note: + +@quotation +This is the patched assembler, to patch SR#1653-010439, where the +assembler aborts on floating point constants. + +The bug is not really in the assembler, but in the shared library +version of the function ``cvtnum(3c)''. The bug on ``cvtnum(3c)'' is +SR#4701-078451. Anyway, the attached assembler uses the archive +library version of ``cvtnum(3c)'' and thus does not exhibit the bug. +@end quotation + +This patch is also known as PHCO_4484. + +@item +On HP-UX version 8.05, but not on 8.07 or more recent versions, +the @code{fixproto} shell script triggers a bug in the system shell. +If you encounter this problem, upgrade your operating system or +use BASH (the GNU shell) to run @code{fixproto}. + +@item +Some versions of the Pyramid C compiler are reported to be unable to +compile GNU CC. You must use an older version of GNU CC for +bootstrapping. One indication of this problem is if you get a crash +when GNU CC compiles the function @code{muldi3} in file @file{libgcc2.c}. + +You may be able to succeed by getting GNU CC version 1, installing it, +and using it to compile GNU CC version 2. The bug in the Pyramid C +compiler does not seem to affect GNU CC version 1. + +@item +There may be similar problems on System V Release 3.1 on 386 systems. + +@item +On the Intel Paragon (an i860 machine), if you are using operating +system version 1.0, you will get warnings or errors about redefinition +of @code{va_arg} when you build GNU CC. + +If this happens, then you need to link most programs with the library +@file{iclib.a}. You must also modify @file{stdio.h} as follows: before +the lines + +@example +#if defined(__i860__) && !defined(_VA_LIST) +#include <va_list.h> +@end example + +@noindent +insert the line + +@example +#if __PGC__ +@end example + +@noindent +and after the lines + +@example +extern int vprintf(const char *, va_list ); +extern int vsprintf(char *, const char *, va_list ); +#endif +@end example + +@noindent +insert the line + +@example +#endif /* __PGC__ */ +@end example + +These problems don't exist in operating system version 1.1. + +@item +On the Altos 3068, programs compiled with GNU CC won't work unless you +fix a kernel bug. This happens using system versions V.2.2 1.0gT1 and +V.2.2 1.0e and perhaps later versions as well. See the file +@file{README.ALTOS}. + +@item +You will get several sorts of compilation and linking errors on the +we32k if you don't follow the special instructions. @xref{Configurations}. + +@item +A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto +program to report an error of the form: + +@example +./fixproto: sh internal 1K buffer overflow +@end example + +To fix this, change the first line of the fixproto script to look like: + +@example +#!/bin/ksh +@end example +@end itemize + +@node Cross-Compiler Problems +@section Cross-Compiler Problems + +You may run into problems with cross compilation on certain machines, +for several reasons. + +@itemize @bullet +@item +Cross compilation can run into trouble for certain machines because +some target machines' assemblers require floating point numbers to be +written as @emph{integer} constants in certain contexts. + +The compiler writes these integer constants by examining the floating +point value as an integer and printing that integer, because this is +simple to write and independent of the details of the floating point +representation. But this does not work if the compiler is running on +a different machine with an incompatible floating point format, or +even a different byte-ordering. + +In addition, correct constant folding of floating point values +requires representing them in the target machine's format. +(The C standard does not quite require this, but in practice +it is the only way to win.) + +It is now possible to overcome these problems by defining macros such +as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of +work for each target machine. +@ifset INTERNALS +@xref{Cross-compilation}. +@end ifset +@ifclear INTERNALS +@xref{Cross-compilation,,Cross Compilation and Floating Point Format, +gcc.info, Using and Porting GCC}. +@end ifclear + +@item +At present, the program @file{mips-tfile} which adds debug +support to object files on MIPS systems does not work in a cross +compile environment. +@end itemize + +@node Interoperation +@section Interoperation + +This section lists various difficulties encountered in using GNU C or +GNU C++ together with other compilers or with the assemblers, linkers, +libraries and debuggers on certain systems. + +@itemize @bullet +@item +Objective C does not work on the RS/6000. + +@item +GNU C++ does not do name mangling in the same way as other C++ +compilers. This means that object files compiled with one compiler +cannot be used with another. + +This effect is intentional, to protect you from more subtle problems. +Compilers differ as to many internal details of C++ implementation, +including: how class instances are laid out, how multiple inheritance is +implemented, and how virtual function calls are handled. If the name +encoding were made the same, your programs would link against libraries +provided from other compilers---but the programs would then crash when +run. Incompatible libraries are then detected at link time, rather than +at run time. + +@item +Older GDB versions sometimes fail to read the output of GNU CC version +2. If you have trouble, get GDB version 4.4 or later. + +@item +@cindex DBX +DBX rejects some files produced by GNU CC, though it accepts similar +constructs in output from PCC. Until someone can supply a coherent +description of what is valid DBX input and what is not, there is +nothing I can do about these problems. You are on your own. + +@item +The GNU assembler (GAS) does not support PIC. To generate PIC code, you +must use some other assembler, such as @file{/bin/as}. + +@item +On some BSD systems, including some versions of Ultrix, use of profiling +causes static variable destructors (currently used only in C++) not to +be run. + +@item +Use of @samp{-I/usr/include} may cause trouble. + +Many systems come with header files that won't work with GNU CC unless +corrected by @code{fixincludes}. The corrected header files go in a new +directory; GNU CC searches this directory before @file{/usr/include}. +If you use @samp{-I/usr/include}, this tells GNU CC to search +@file{/usr/include} earlier on, before the corrected headers. The +result is that you get the uncorrected header files. + +Instead, you should use these options (when compiling C programs): + +@smallexample +-I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include +@end smallexample + +For C++ programs, GNU CC also uses a special directory that defines C++ +interfaces to standard C subroutines. This directory is meant to be +searched @emph{before} other standard include directories, so that it +takes precedence. If you are compiling C++ programs and specifying +include directories explicitly, use this option first, then the two +options above: + +@example +-I/usr/local/lib/g++-include +@end example + +@ignore +@cindex @code{vfork}, for the Sun-4 +@item +There is a bug in @code{vfork} on the Sun-4 which causes the registers +of the child process to clobber those of the parent. Because of this, +programs that call @code{vfork} are likely to lose when compiled +optimized with GNU CC when the child code alters registers which contain +C variables in the parent. This affects variables which are live in the +parent across the call to @code{vfork}. + +If you encounter this, you can work around the problem by declaring +variables @code{volatile} in the function that calls @code{vfork}, until +the problem goes away, or by not declaring them @code{register} and not +using @samp{-O} for those source files. +@end ignore + +@item +On some SGI systems, when you use @samp{-lgl_s} as an option, +it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}. +Naturally, this does not happen when you use GNU CC. +You must specify all three options explicitly. + +@item +On a Sparc, GNU CC aligns all values of type @code{double} on an 8-byte +boundary, and it expects every @code{double} to be so aligned. The Sun +compiler usually gives @code{double} values 8-byte alignment, with one +exception: function arguments of type @code{double} may not be aligned. + +As a result, if a function compiled with Sun CC takes the address of an +argument of type @code{double} and passes this pointer of type +@code{double *} to a function compiled with GNU CC, dereferencing the +pointer may cause a fatal signal. + +One way to solve this problem is to compile your entire program with GNU +CC. Another solution is to modify the function that is compiled with +Sun CC to copy the argument into a local variable; local variables +are always properly aligned. A third solution is to modify the function +that uses the pointer to dereference it via the following function +@code{access_double} instead of directly with @samp{*}: + +@smallexample +inline double +access_double (double *unaligned_ptr) +@{ + union d2i @{ double d; int i[2]; @}; + + union d2i *p = (union d2i *) unaligned_ptr; + union d2i u; + + u.i[0] = p->i[0]; + u.i[1] = p->i[1]; + + return u.d; +@} +@end smallexample + +@noindent +Storing into the pointer can be done likewise with the same union. + +@item +On Solaris, the @code{malloc} function in the @file{libmalloc.a} library +may allocate memory that is only 4 byte aligned. Since GNU CC on the +Sparc assumes that doubles are 8 byte aligned, this may result in a +fatal signal if doubles are stored in memory allocated by the +@file{libmalloc.a} library. + +The solution is to not use the @file{libmalloc.a} library. Use instead +@code{malloc} and related functions from @file{libc.a}; they do not have +this problem. + +@item +Sun forgot to include a static version of @file{libdl.a} with some +versions of SunOS (mainly 4.1). This results in undefined symbols when +linking static binaries (that is, if you use @samp{-static}). If you +see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen} +when linking, compile and link against the file +@file{mit/util/misc/dlsym.c} from the MIT version of X windows. + +@item +The 128-bit long double format that the Sparc port supports currently +works by using the architecturally defined quad-word floating point +instructions. Since there is no hardware that supports these +instructions they must be emulated by the operating system. Long +doubles do not work in Sun OS versions 4.0.3 and earlier, because the +kernel emulator uses an obsolete and incompatible format. Long doubles +do not work in Sun OS version 4.1.1 due to a problem in a Sun library. +Long doubles do work on Sun OS versions 4.1.2 and higher, but GNU CC +does not enable them by default. Long doubles appear to work in Sun OS +5.x (Solaris 2.x). + +@item +On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not +compile GNU CC correctly. We do not yet know why. However, GNU CC +compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can +compile itself properly on 9.01. + +@item +On the HP PA machine, ADB sometimes fails to work on functions compiled +with GNU CC. Specifically, it fails to work on functions that use +@code{alloca} or variable-size arrays. This is because GNU CC doesn't +generate HP-UX unwind descriptors for such functions. It may even be +impossible to generate them. + +@item +Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use +the preliminary GNU tools (@pxref{Installation}). + +@item +Taking the address of a label may generate errors from the HP-UX +PA assembler. GAS for the PA does not have this problem. + +@item +Using floating point parameters for indirect calls to static functions +will not work when using the HP assembler. There simply is no way for GCC +to specify what registers hold arguments for static functions when using +the HP assembler. GAS for the PA does not have this problem. + +@item +In extremely rare cases involving some very large functions you may +receive errors from the HP linker complaining about an out of bounds +unconditional branch offset. This used to occur more often in previous +versions of GNU CC, but is now exceptionally rare. If you should run +into it, you can work around by making your function smaller. + +@item +GNU CC compiled code sometimes emits warnings from the HP-UX assembler of +the form: + +@smallexample +(warning) Use of GR3 when + frame >= 8192 may cause conflict. +@end smallexample + +These warnings are harmless and can be safely ignored. + +@item +The current version of the assembler (@file{/bin/as}) for the RS/6000 +has certain problems that prevent the @samp{-g} option in GCC from +working. Note that @file{Makefile.in} uses @samp{-g} by default when +compiling @file{libgcc2.c}. + +IBM has produced a fixed version of the assembler. The upgraded +assembler unfortunately was not included in any of the AIX 3.2 update +PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request +PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277. +See the file @file{README.RS6000} for more details on these updates. + +You can test for the presense of a fixed assembler by using the +command + +@smallexample +as -u < /dev/null +@end smallexample + +@noindent +If the command exits normally, the assembler fix already is installed. +If the assembler complains that "-u" is an unknown flag, you need to +order the fix. + +@item +On the IBM RS/6000, compiling code of the form + +@smallexample +extern int foo; + +@dots{} foo @dots{} + +static int foo; +@end smallexample + +@noindent +will cause the linker to report an undefined symbol @code{foo}. +Although this behavior differs from most other systems, it is not a +bug because redefining an @code{extern} variable as @code{static} +is undefined in ANSI C. + +@item +AIX on the RS/6000 provides support (NLS) for environments outside of +the United States. Compilers and assemblers use NLS to support +locale-specific representations of various objects including +floating-point numbers ("." vs "," for separating decimal fractions). +There have been problems reported where the library linked with GCC does +not produce the same floating-point formats that the assembler accepts. +If you have this problem, set the LANG environment variable to "C" or +"En_US". + +@item +Even if you specify @samp{-fdollars-in-identifiers}, +you cannot successfully use @samp{$} in identifiers on the RS/6000 due +to a restriction in the IBM assembler. GAS supports these +identifiers. + +@item +On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC +version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2 +by requesting PTF 421749 from IBM. + +@item +There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that +occurs when the @samp{fldcr} instruction is used. GNU CC uses +@samp{fldcr} on the 88100 to serialize volatile memory references. Use +the option @samp{-mno-serialize-volatile} if your version of the +assembler has this bug. + +@item +On VMS, GAS versions 1.38.1 and earlier may cause spurious warning +messages from the linker. These warning messages complain of mismatched +psect attributes. You can ignore them. @xref{VMS Install}. + +@item +On NewsOS version 3, if you include both of the files @file{stddef.h} +and @file{sys/types.h}, you get an error because there are two typedefs +of @code{size_t}. You should change @file{sys/types.h} by adding these +lines around the definition of @code{size_t}: + +@smallexample +#ifndef _SIZE_T +#define _SIZE_T +@var{actual typedef here} +#endif +@end smallexample + +@cindex Alliant +@item +On the Alliant, the system's own convention for returning structures +and unions is unusual, and is not compatible with GNU CC no matter +what options are used. + +@cindex RT PC +@cindex IBM RT PC +@item +On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different +convention for structure and union returning. Use the option +@samp{-mhc-struct-return} to tell GNU CC to use a convention compatible +with it. + +@cindex Vax calling convention +@cindex Ultrix calling convention +@item +On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved +by function calls. However, the C compiler uses conventions compatible +with BSD Unix: registers 2 through 5 may be clobbered by function calls. + +GNU CC uses the same convention as the Ultrix C compiler. You can use +these options to produce code compatible with the Fortran compiler: + +@smallexample +-fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5 +@end smallexample + +@item +On the WE32k, you may find that programs compiled with GNU CC do not +work with the standard shared C library. You may need to link with +the ordinary C compiler. If you do so, you must specify the following +options: + +@smallexample +-L/usr/local/lib/gcc-lib/we32k-att-sysv/2.7.1 -lgcc -lc_s +@end smallexample + +The first specifies where to find the library @file{libgcc.a} +specified with the @samp{-lgcc} option. + +GNU CC does linking by invoking @code{ld}, just as @code{cc} does, and +there is no reason why it @emph{should} matter which compilation program +you use to invoke @code{ld}. If someone tracks this problem down, +it can probably be fixed easily. + +@item +On the Alpha, you may get assembler errors about invalid syntax as a +result of floating point constants. This is due to a bug in the C +library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid +floating point numbers, they sometimes print @samp{NaN}. + +@item +On Irix 4.0.5F (and perhaps in some other versions), an assembler bug +sometimes reorders instructions incorrectly when optimization is turned +on. If you think this may be happening to you, try using the GNU +assembler; GAS version 2.1 supports ECOFF on Irix. + +Or use the @samp{-noasmopt} option when you compile GNU CC with itself, +and then again when you compile your program. (This is a temporary +kludge to turn off assembler optimization on Irix.) If this proves to +be what you need, edit the assembler spec in the file @file{specs} so +that it unconditionally passes @samp{-O0} to the assembler, and never +passes @samp{-O2} or @samp{-O3}. +@end itemize + +@node External Bugs +@section Problems Compiling Certain Programs + +@c prevent bad page break with this line +Certain programs have problems compiling. + +@itemize @bullet +@item +Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2 +because of problems in DEC's versions of the X11 header files +@file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding +@samp{-I/usr/include/mit} to use the MIT versions of the header files, +using the @samp{-traditional} switch to turn off ANSI C, or fixing the +header files by adding this: + +@example +#ifdef __STDC__ +#define NeedFunctionPrototypes 0 +#endif +@end example + +@item +If you have trouble compiling Perl on a SunOS 4 system, it may be +because Perl specifies @samp{-I/usr/ucbinclude}. This accesses the +unfixed header files. Perl specifies the options + +@example +-traditional -Dvolatile=__volatile__ +-I/usr/include/sun -I/usr/ucbinclude +-fpcc-struct-return +@end example + +@noindent +most of which are unnecessary with GCC 2.4.5 and newer versions. You +can make a properly working Perl by setting @code{ccflags} to +@samp{-fwritable-strings} (implied by the @samp{-traditional} in the +original options) and @code{cppflags} to empty in @file{config.sh}, then +typing @samp{./doSH; make depend; make}. + +@item +On various 386 Unix systems derived from System V, including SCO, ISC, +and ESIX, you may get error messages about running out of virtual memory +while compiling certain programs. + +You can prevent this problem by linking GNU CC with the GNU malloc +(which thus replaces the malloc that comes with the system). GNU malloc +is available as a separate package, and also in the file +@file{src/gmalloc.c} in the GNU Emacs 19 distribution. + +If you have installed GNU malloc as a separate library package, use this +option when you relink GNU CC: + +@example +MALLOC=/usr/local/lib/libgmalloc.a +@end example + +Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy +the object file to @file{gmalloc.o} and use this option when you relink +GNU CC: + +@example +MALLOC=gmalloc.o +@end example +@end itemize + +@node Incompatibilities +@section Incompatibilities of GNU CC +@cindex incompatibilities of GNU CC + +There are several noteworthy incompatibilities between GNU C and most +existing (non-ANSI) versions of C. The @samp{-traditional} option +eliminates many of these incompatibilities, @emph{but not all}, by +telling GNU C to behave like the other C compilers. + +@itemize @bullet +@cindex string constants +@cindex read-only strings +@cindex shared strings +@item +GNU CC normally makes string constants read-only. If several +identical-looking string constants are used, GNU CC stores only one +copy of the string. + +@cindex @code{mktemp}, and constant strings +One consequence is that you cannot call @code{mktemp} with a string +constant argument. The function @code{mktemp} always alters the +string its argument points to. + +@cindex @code{sscanf}, and constant strings +@cindex @code{fscanf}, and constant strings +@cindex @code{scanf}, and constant strings +Another consequence is that @code{sscanf} does not work on some systems +when passed a string constant as its format control string or input. +This is because @code{sscanf} incorrectly tries to write into the string +constant. Likewise @code{fscanf} and @code{scanf}. + +The best solution to these problems is to change the program to use +@code{char}-array variables with initialization strings for these +purposes instead of string constants. But if this is not possible, +you can use the @samp{-fwritable-strings} flag, which directs GNU CC +to handle string constants the same way most C compilers do. +@samp{-traditional} also has this effect, among others. + +@item +@code{-2147483648} is positive. + +This is because 2147483648 cannot fit in the type @code{int}, so +(following the ANSI C rules) its data type is @code{unsigned long int}. +Negating this value yields 2147483648 again. + +@item +GNU CC does not substitute macro arguments when they appear inside of +string constants. For example, the following macro in GNU CC + +@example +#define foo(a) "a" +@end example + +@noindent +will produce output @code{"a"} regardless of what the argument @var{a} is. + +The @samp{-traditional} option directs GNU CC to handle such cases +(among others) in the old-fashioned (non-ANSI) fashion. + +@cindex @code{setjmp} incompatibilities +@cindex @code{longjmp} incompatibilities +@item +When you use @code{setjmp} and @code{longjmp}, the only automatic +variables guaranteed to remain valid are those declared +@code{volatile}. This is a consequence of automatic register +allocation. Consider this function: + +@example +jmp_buf j; + +foo () +@{ + int a, b; + + a = fun1 (); + if (setjmp (j)) + return a; + + a = fun2 (); + /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */ + return a + fun3 (); +@} +@end example + +Here @code{a} may or may not be restored to its first value when the +@code{longjmp} occurs. If @code{a} is allocated in a register, then +its first value is restored; otherwise, it keeps the last value stored +in it. + +If you use the @samp{-W} option with the @samp{-O} option, you will +get a warning when GNU CC thinks such a problem might be possible. + +The @samp{-traditional} option directs GNU C to put variables in +the stack by default, rather than in registers, in functions that +call @code{setjmp}. This results in the behavior found in +traditional C compilers. + +@item +Programs that use preprocessing directives in the middle of macro +arguments do not work with GNU CC. For example, a program like this +will not work: + +@example +foobar ( +#define luser + hack) +@end example + +ANSI C does not permit such a construct. It would make sense to support +it when @samp{-traditional} is used, but it is too much work to +implement. + +@cindex external declaration scope +@cindex scope of external declarations +@cindex declaration scope +@item +Declarations of external variables and functions within a block apply +only to the block containing the declaration. In other words, they +have the same scope as any other declaration in the same place. + +In some other C compilers, a @code{extern} declaration affects all the +rest of the file even if it happens within a block. + +The @samp{-traditional} option directs GNU C to treat all @code{extern} +declarations as global, like traditional compilers. + +@item +In traditional C, you can combine @code{long}, etc., with a typedef name, +as shown here: + +@example +typedef int foo; +typedef long foo bar; +@end example + +In ANSI C, this is not allowed: @code{long} and other type modifiers +require an explicit @code{int}. Because this criterion is expressed +by Bison grammar rules rather than C code, the @samp{-traditional} +flag cannot alter it. + +@cindex typedef names as function parameters +@item +PCC allows typedef names to be used as function parameters. The +difficulty described immediately above applies here too. + +@cindex whitespace +@item +PCC allows whitespace in the middle of compound assignment operators +such as @samp{+=}. GNU CC, following the ANSI standard, does not +allow this. The difficulty described immediately above applies here +too. + +@cindex apostrophes +@cindex ' +@item +GNU CC complains about unterminated character constants inside of +preprocessing conditionals that fail. Some programs have English +comments enclosed in conditionals that are guaranteed to fail; if these +comments contain apostrophes, GNU CC will probably report an error. For +example, this code would produce an error: + +@example +#if 0 +You can't expect this to work. +#endif +@end example + +The best solution to such a problem is to put the text into an actual +C comment delimited by @samp{/*@dots{}*/}. However, +@samp{-traditional} suppresses these error messages. + +@item +Many user programs contain the declaration @samp{long time ();}. In the +past, the system header files on many systems did not actually declare +@code{time}, so it did not matter what type your program declared it to +return. But in systems with ANSI C headers, @code{time} is declared to +return @code{time_t}, and if that is not the same as @code{long}, then +@samp{long time ();} is erroneous. + +The solution is to change your program to use @code{time_t} as the return +type of @code{time}. + +@cindex @code{float} as function value type +@item +When compiling functions that return @code{float}, PCC converts it to +a double. GNU CC actually returns a @code{float}. If you are concerned +with PCC compatibility, you should declare your functions to return +@code{double}; you might as well say what you mean. + +@cindex structures +@cindex unions +@item +When compiling functions that return structures or unions, GNU CC +output code normally uses a method different from that used on most +versions of Unix. As a result, code compiled with GNU CC cannot call +a structure-returning function compiled with PCC, and vice versa. + +The method used by GNU CC is as follows: a structure or union which is +1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union +with any other size is stored into an address supplied by the caller +(usually in a special, fixed register, but on some machines it is passed +on the stack). The machine-description macros @code{STRUCT_VALUE} and +@code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address. + +By contrast, PCC on most target machines returns structures and unions +of any size by copying the data into an area of static storage, and then +returning the address of that storage as if it were a pointer value. +The caller must copy the data from that memory area to the place where +the value is wanted. GNU CC does not use this method because it is +slower and nonreentrant. + +On some newer machines, PCC uses a reentrant convention for all +structure and union returning. GNU CC on most of these machines uses a +compatible convention when returning structures and unions in memory, +but still returns small structures and unions in registers. + +You can tell GNU CC to use a compatible convention for all structure and +union returning with the option @samp{-fpcc-struct-return}. + +@cindex preprocessing tokens +@cindex preprocessing numbers +@item +GNU C complains about program fragments such as @samp{0x74ae-0x4000} +which appear to be two hexadecimal constants separated by the minus +operator. Actually, this string is a single @dfn{preprocessing token}. +Each such token must correspond to one token in C. Since this does not, +GNU C prints an error message. Although it may appear obvious that what +is meant is an operator and two values, the ANSI C standard specifically +requires that this be treated as erroneous. + +A @dfn{preprocessing token} is a @dfn{preprocessing number} if it +begins with a digit and is followed by letters, underscores, digits, +periods and @samp{e+}, @samp{e-}, @samp{E+}, or @samp{E-} character +sequences. + +To make the above program fragment valid, place whitespace in front of +the minus sign. This whitespace will end the preprocessing number. +@end itemize + +@node Fixed Headers +@section Fixed Header Files + +GNU CC needs to install corrected versions of some system header files. +This is because most target systems have some header files that won't +work with GNU CC unless they are changed. Some have bugs, some are +incompatible with ANSI C, and some depend on special features of other +compilers. + +Installing GNU CC automatically creates and installs the fixed header +files, by running a program called @code{fixincludes} (or for certain +targets an alternative such as @code{fixinc.svr4}). Normally, you +don't need to pay attention to this. But there are cases where it +doesn't do the right thing automatically. + +@itemize @bullet +@item +If you update the system's header files, such as by installing a new +system version, the fixed header files of GNU CC are not automatically +updated. The easiest way to update them is to reinstall GNU CC. (If +you want to be clever, look in the makefile and you can find a +shortcut.) + +@item +On some systems, in particular SunOS 4, header file directories contain +machine-specific symbolic links in certain places. This makes it +possible to share most of the header files among hosts running the +same version of SunOS 4 on different machine models. + +The programs that fix the header files do not understand this special +way of using symbolic links; therefore, the directory of fixed header +files is good only for the machine model used to build it. + +In SunOS 4, only programs that look inside the kernel will notice the +difference between machine models. Therefore, for most purposes, you +need not be concerned about this. + +It is possible to make separate sets of fixed header files for the +different machine models, and arrange a structure of symbolic links so +as to use the proper set, but you'll have to do this by hand. + +@item +On Lynxos, GNU CC by default does not fix the header files. This is +because bugs in the shell cause the @code{fixincludes} script to fail. + +This means you will encounter problems due to bugs in the system header +files. It may be no comfort that they aren't GNU CC's fault, but it +does mean that there's nothing for us to do about them. +@end itemize + +@node Standard Libraries +@section Standard Libraries + +GNU CC by itself attempts to be what the ISO/ANSI C standard calls a +@dfn{conforming freestanding implementation}. This means all ANSI +C language features are available, as well as the contents of +@file{float.h}, @file{limits.h}, @file{stdarg.h}, and +@file{stddef.h}. The rest of the C library is supplied by the +vendor of the operating system. If that C library doesn't conform to +the C standards, then your programs might get warnings (especially when +using @samp{-Wall}) that you don't expect. + +For example, the @code{sprintf} function on SunOS 4.1.3 returns +@code{char *} while the C standard says that @code{sprintf} returns an +@code{int}. The @code{fixincludes} program could make the prototype for +this function match the Standard, but that would be wrong, since the +function will still return @code{char *}. + +If you need a Standard compliant library, then you need to find one, as +GNU CC does not provide one. The GNU C library (called @code{glibc}) +has been ported to a number of operating systems, and provides ANSI/ISO, +POSIX, BSD and SystemV compatibility. You could also ask your operating +system vendor if newer libraries are available. + +@node Disappointments +@section Disappointments and Misunderstandings + +These problems are perhaps regrettable, but we don't know any practical +way around them. + +@itemize @bullet +@item +Certain local variables aren't recognized by debuggers when you compile +with optimization. + +This occurs because sometimes GNU CC optimizes the variable out of +existence. There is no way to tell the debugger how to compute the +value such a variable ``would have had'', and it is not clear that would +be desirable anyway. So GNU CC simply does not mention the eliminated +variable when it writes debugging information. + +You have to expect a certain amount of disagreement between the +executable and your source code, when you use optimization. + +@cindex conflicting types +@cindex scope of declaration +@item +Users often think it is a bug when GNU CC reports an error for code +like this: + +@example +int foo (struct mumble *); + +struct mumble @{ @dots{} @}; + +int foo (struct mumble *x) +@{ @dots{} @} +@end example + +This code really is erroneous, because the scope of @code{struct +mumble} in the prototype is limited to the argument list containing it. +It does not refer to the @code{struct mumble} defined with file scope +immediately below---they are two unrelated types with similar names in +different scopes. + +But in the definition of @code{foo}, the file-scope type is used +because that is available to be inherited. Thus, the definition and +the prototype do not match, and you get an error. + +This behavior may seem silly, but it's what the ANSI standard specifies. +It is easy enough for you to make your code work by moving the +definition of @code{struct mumble} above the prototype. It's not worth +being incompatible with ANSI C just to avoid an error for the example +shown above. + +@item +Accesses to bitfields even in volatile objects works by accessing larger +objects, such as a byte or a word. You cannot rely on what size of +object is accessed in order to read or write the bitfield; it may even +vary for a given bitfield according to the precise usage. + +If you care about controlling the amount of memory that is accessed, use +volatile but do not use bitfields. + +@item +GNU CC comes with shell scripts to fix certain known problems in system +header files. They install corrected copies of various header files in +a special directory where only GNU CC will normally look for them. The +scripts adapt to various systems by searching all the system header +files for the problem cases that we know about. + +If new system header files are installed, nothing automatically arranges +to update the corrected header files. You will have to reinstall GNU CC +to fix the new header files. More specifically, go to the build +directory and delete the files @file{stmp-fixinc} and +@file{stmp-headers}, and the subdirectory @code{include}; then do +@samp{make install} again. + +@item +On 68000 systems, you can get paradoxical results if you test the +precise values of floating point numbers. For example, you can find +that a floating point value which is not a NaN is not equal to itself. +This results from the fact that the the floating point registers hold a +few more bits of precision than fit in a @code{double} in memory. +Compiled code moves values between memory and floating point registers +at its convenience, and moving them into memory truncates them. + +You can partially avoid this problem by using the @samp{-ffloat-store} +option (@pxref{Optimize Options}). + +@item +On the MIPS, variable argument functions using @file{varargs.h} +cannot have a floating point value for the first argument. The +reason for this is that in the absence of a prototype in scope, +if the first argument is a floating point, it is passed in a +floating point register, rather than an integer register. + +If the code is rewritten to use the ANSI standard @file{stdarg.h} +method of variable arguments, and the prototype is in scope at +the time of the call, everything will work fine. +@end itemize + +@node C++ Misunderstandings +@section Common Misunderstandings with GNU C++ + +@cindex misunderstandings in C++ +@cindex surprises in C++ +@cindex C++ misunderstandings +C++ is a complex language and an evolving one, and its standard definition +(the ANSI C++ draft standard) is also evolving. As a result, +your C++ compiler may occasionally surprise you, even when its behavior is +correct. This section discusses some areas that frequently give rise to +questions of this sort. + +@menu +* Static Definitions:: Static member declarations are not definitions +* Temporaries:: Temporaries may vanish before you expect +@end menu + +@node Static Definitions +@subsection Declare @emph{and} Define Static Members + +@cindex C++ static data, declaring and defining +@cindex static data in C++, declaring and defining +@cindex declaring static data in C++ +@cindex defining static data in C++ +When a class has static data members, it is not enough to @emph{declare} +the static member; you must also @emph{define} it. For example: + +@example +class Foo +@{ + @dots{} + void method(); + static int bar; +@}; +@end example + +This declaration only establishes that the class @code{Foo} has an +@code{int} named @code{Foo::bar}, and a member function named +@code{Foo::method}. But you still need to define @emph{both} +@code{method} and @code{bar} elsewhere. According to the draft ANSI +standard, you must supply an initializer in one (and only one) source +file, such as: + +@example +int Foo::bar = 0; +@end example + +Other C++ compilers may not correctly implement the standard behavior. +As a result, when you switch to @code{g++} from one of these compilers, +you may discover that a program that appeared to work correctly in fact +does not conform to the standard: @code{g++} reports as undefined +symbols any static data members that lack definitions. + +@node Temporaries +@subsection Temporaries May Vanish Before You Expect + +@cindex temporaries, lifetime of +@cindex portions of temporary objects, pointers to +It is dangerous to use pointers or references to @emph{portions} of a +temporary object. The compiler may very well delete the object before +you expect it to, leaving a pointer to garbage. The most common place +where this problem crops up is in classes like the libg++ +@code{String} class, that define a conversion function to type +@code{char *} or @code{const char *}. However, any class that returns +a pointer to some internal structure is potentially subject to this +problem. + +For example, a program may use a function @code{strfunc} that returns +@code{String} objects, and another function @code{charfunc} that +operates on pointers to @code{char}: + +@example +String strfunc (); +void charfunc (const char *); +@end example + +@noindent +In this situation, it may seem natural to write @w{@samp{charfunc +(strfunc ());}} based on the knowledge that class @code{String} has an +explicit conversion to @code{char} pointers. However, what really +happens is akin to @samp{charfunc (@w{strfunc ()}.@w{convert ()});}, +where the @code{convert} method is a function to do the same data +conversion normally performed by a cast. Since the last use of the +temporary @code{String} object is the call to the conversion function, +the compiler may delete that object before actually calling +@code{charfunc}. The compiler has no way of knowing that deleting the +@code{String} object will invalidate the pointer. The pointer then +points to garbage, so that by the time @code{charfunc} is called, it +gets an invalid argument. + +Code like this may run successfully under some other compilers, +especially those that delete temporaries relatively late. However, the +GNU C++ behavior is also standard-conforming, so if your program depends +on late destruction of temporaries it is not portable. + +If you think this is surprising, you should be aware that the ANSI C++ +committee continues to debate the lifetime-of-temporaries problem. + +For now, at least, the safe way to write such code is to give the +temporary a name, which forces it to remain until the end of the scope of +the name. For example: + +@example +String& tmp = strfunc (); +charfunc (tmp); +@end example + +@node Protoize Caveats +@section Caveats of using @code{protoize} + +The conversion programs @code{protoize} and @code{unprotoize} can +sometimes change a source file in a way that won't work unless you +rearrange it. + +@itemize @bullet +@item +@code{protoize} can insert references to a type name or type tag before +the definition, or in a file where they are not defined. + +If this happens, compiler error messages should show you where the new +references are, so fixing the file by hand is straightforward. + +@item +There are some C constructs which @code{protoize} cannot figure out. +For example, it can't determine argument types for declaring a +pointer-to-function variable; this you must do by hand. @code{protoize} +inserts a comment containing @samp{???} each time it finds such a +variable; so you can find all such variables by searching for this +string. ANSI C does not require declaring the argument types of +pointer-to-function types. + +@item +Using @code{unprotoize} can easily introduce bugs. If the program +relied on prototypes to bring about conversion of arguments, these +conversions will not take place in the program without prototypes. +One case in which you can be sure @code{unprotoize} is safe is when +you are removing prototypes that were made with @code{protoize}; if +the program worked before without any prototypes, it will work again +without them. + +You can find all the places where this problem might occur by compiling +the program with the @samp{-Wconversion} option. It prints a warning +whenever an argument is converted. + +@item +Both conversion programs can be confused if there are macro calls in and +around the text to be converted. In other words, the standard syntax +for a declaration or definition must not result from expanding a macro. +This problem is inherent in the design of C and cannot be fixed. If +only a few functions have confusing macro calls, you can easily convert +them manually. + +@item +@code{protoize} cannot get the argument types for a function whose +definition was not actually compiled due to preprocessing conditionals. +When this happens, @code{protoize} changes nothing in regard to such +a function. @code{protoize} tries to detect such instances and warn +about them. + +You can generally work around this problem by using @code{protoize} step +by step, each time specifying a different set of @samp{-D} options for +compilation, until all of the functions have been converted. There is +no automatic way to verify that you have got them all, however. + +@item +Confusion may result if there is an occasion to convert a function +declaration or definition in a region of source code where there is more +than one formal parameter list present. Thus, attempts to convert code +containing multiple (conditionally compiled) versions of a single +function header (in the same vicinity) may not produce the desired (or +expected) results. + +If you plan on converting source files which contain such code, it is +recommended that you first make sure that each conditionally compiled +region of source code which contains an alternative function header also +contains at least one additional follower token (past the final right +parenthesis of the function header). This should circumvent the +problem. + +@item +@code{unprotoize} can become confused when trying to convert a function +definition or declaration which contains a declaration for a +pointer-to-function formal argument which has the same name as the +function being defined or declared. We recommand you avoid such choices +of formal parameter names. + +@item +You might also want to correct some of the indentation by hand and break +long lines. (The conversion programs don't write lines longer than +eighty characters in any case.) +@end itemize + +@node Non-bugs +@section Certain Changes We Don't Want to Make + +This section lists changes that people frequently request, but which +we do not make because we think GNU CC is better without them. + +@itemize @bullet +@item +Checking the number and type of arguments to a function which has an +old-fashioned definition and no prototype. + +Such a feature would work only occasionally---only for calls that appear +in the same file as the called function, following the definition. The +only way to check all calls reliably is to add a prototype for the +function. But adding a prototype eliminates the motivation for this +feature. So the feature is not worthwhile. + +@item +Warning about using an expression whose type is signed as a shift count. + +Shift count operands are probably signed more often than unsigned. +Warning about this would cause far more annoyance than good. + +@item +Warning about assigning a signed value to an unsigned variable. + +Such assignments must be very common; warning about them would cause +more annoyance than good. + +@item +Warning about unreachable code. + +It's very common to have unreachable code in machine-generated +programs. For example, this happens normally in some files of GNU C +itself. + +@item +Warning when a non-void function value is ignored. + +Coming as I do from a Lisp background, I balk at the idea that there is +something dangerous about discarding a value. There are functions that +return values which some callers may find useful; it makes no sense to +clutter the program with a cast to @code{void} whenever the value isn't +useful. + +@item +Assuming (for optimization) that the address of an external symbol is +never zero. + +This assumption is false on certain systems when @samp{#pragma weak} is +used. + +@item +Making @samp{-fshort-enums} the default. + +This would cause storage layout to be incompatible with most other C +compilers. And it doesn't seem very important, given that you can get +the same result in other ways. The case where it matters most is when +the enumeration-valued object is inside a structure, and in that case +you can specify a field width explicitly. + +@item +Making bitfields unsigned by default on particular machines where ``the +ABI standard'' says to do so. + +The ANSI C standard leaves it up to the implementation whether a bitfield +declared plain @code{int} is signed or not. This in effect creates two +alternative dialects of C. + +The GNU C compiler supports both dialects; you can specify the signed +dialect with @samp{-fsigned-bitfields} and the unsigned dialect with +@samp{-funsigned-bitfields}. However, this leaves open the question of +which dialect to use by default. + +Currently, the preferred dialect makes plain bitfields signed, because +this is simplest. Since @code{int} is the same as @code{signed int} in +every other context, it is cleanest for them to be the same in bitfields +as well. + +Some computer manufacturers have published Application Binary Interface +standards which specify that plain bitfields should be unsigned. It is +a mistake, however, to say anything about this issue in an ABI. This is +because the handling of plain bitfields distinguishes two dialects of C. +Both dialects are meaningful on every type of machine. Whether a +particular object file was compiled using signed bitfields or unsigned +is of no concern to other object files, even if they access the same +bitfields in the same data structures. + +A given program is written in one or the other of these two dialects. +The program stands a chance to work on most any machine if it is +compiled with the proper dialect. It is unlikely to work at all if +compiled with the wrong dialect. + +Many users appreciate the GNU C compiler because it provides an +environment that is uniform across machines. These users would be +inconvenienced if the compiler treated plain bitfields differently on +certain machines. + +Occasionally users write programs intended only for a particular machine +type. On these occasions, the users would benefit if the GNU C compiler +were to support by default the same dialect as the other compilers on +that machine. But such applications are rare. And users writing a +program to run on more than one type of machine cannot possibly benefit +from this kind of compatibility. + +This is why GNU CC does and will treat plain bitfields in the same +fashion on all types of machines (by default). + +There are some arguments for making bitfields unsigned by default on all +machines. If, for example, this becomes a universal de facto standard, +it would make sense for GNU CC to go along with it. This is something +to be considered in the future. + +(Of course, users strongly concerned about portability should indicate +explicitly in each bitfield whether it is signed or not. In this way, +they write programs which have the same meaning in both C dialects.) + +@item +Undefining @code{__STDC__} when @samp{-ansi} is not used. + +Currently, GNU CC defines @code{__STDC__} as long as you don't use +@samp{-traditional}. This provides good results in practice. + +Programmers normally use conditionals on @code{__STDC__} to ask whether +it is safe to use certain features of ANSI C, such as function +prototypes or ANSI token concatenation. Since plain @samp{gcc} supports +all the features of ANSI C, the correct answer to these questions is +``yes''. + +Some users try to use @code{__STDC__} to check for the availability of +certain library facilities. This is actually incorrect usage in an ANSI +C program, because the ANSI C standard says that a conforming +freestanding implementation should define @code{__STDC__} even though it +does not have the library facilities. @samp{gcc -ansi -pedantic} is a +conforming freestanding implementation, and it is therefore required to +define @code{__STDC__}, even though it does not come with an ANSI C +library. + +Sometimes people say that defining @code{__STDC__} in a compiler that +does not completely conform to the ANSI C standard somehow violates the +standard. This is illogical. The standard is a standard for compilers +that claim to support ANSI C, such as @samp{gcc -ansi}---not for other +compilers such as plain @samp{gcc}. Whatever the ANSI C standard says +is relevant to the design of plain @samp{gcc} without @samp{-ansi} only +for pragmatic reasons, not as a requirement. + +@item +Undefining @code{__STDC__} in C++. + +Programs written to compile with C++-to-C translators get the +value of @code{__STDC__} that goes with the C compiler that is +subsequently used. These programs must test @code{__STDC__} +to determine what kind of C preprocessor that compiler uses: +whether they should concatenate tokens in the ANSI C fashion +or in the traditional fashion. + +These programs work properly with GNU C++ if @code{__STDC__} is defined. +They would not work otherwise. + +In addition, many header files are written to provide prototypes in ANSI +C but not in traditional C. Many of these header files can work without +change in C++ provided @code{__STDC__} is defined. If @code{__STDC__} +is not defined, they will all fail, and will all need to be changed to +test explicitly for C++ as well. + +@item +Deleting ``empty'' loops. + +GNU CC does not delete ``empty'' loops because the most likely reason +you would put one in a program is to have a delay. Deleting them will +not make real programs run any faster, so it would be pointless. + +It would be different if optimization of a nonempty loop could produce +an empty one. But this generally can't happen. + +@item +Making side effects happen in the same order as in some other compiler. + +@cindex side effects, order of evaluation +@cindex order of evaluation, side effects +It is never safe to depend on the order of evaluation of side effects. +For example, a function call like this may very well behave differently +from one compiler to another: + +@example +void func (int, int); + +int i = 2; +func (i++, i++); +@end example + +There is no guarantee (in either the C or the C++ standard language +definitions) that the increments will be evaluated in any particular +order. Either increment might happen first. @code{func} might get the +arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}. + +@item +Not allowing structures with volatile fields in registers. + +Strictly speaking, there is no prohibition in the ANSI C standard +against allowing structures with volatile fields in registers, but +it does not seem to make any sense and is probably not what you wanted +to do. So the compiler will give an error message in this case. +@end itemize + +@node Warnings and Errors +@section Warning Messages and Error Messages + +@cindex error messages +@cindex warnings vs errors +@cindex messages, warning and error +The GNU compiler can produce two kinds of diagnostics: errors and +warnings. Each kind has a different purpose: + +@itemize @w{} +@item +@emph{Errors} report problems that make it impossible to compile your +program. GNU CC reports errors with the source file name and line +number where the problem is apparent. + +@item +@emph{Warnings} report other unusual conditions in your code that +@emph{may} indicate a problem, although compilation can (and does) +proceed. Warning messages also report the source file name and line +number, but include the text @samp{warning:} to distinguish them +from error messages. +@end itemize + +Warnings may indicate danger points where you should check to make sure +that your program really does what you intend; or the use of obsolete +features; or the use of nonstandard features of GNU C or C++. Many +warnings are issued only if you ask for them, with one of the @samp{-W} +options (for instance, @samp{-Wall} requests a variety of useful +warnings). + +GNU CC always tries to compile your program if possible; it never +gratuitously rejects a program whose meaning is clear merely because +(for instance) it fails to conform to a standard. In some cases, +however, the C and C++ standards specify that certain extensions are +forbidden, and a diagnostic @emph{must} be issued by a conforming +compiler. The @samp{-pedantic} option tells GNU CC to issue warnings in +such cases; @samp{-pedantic-errors} says to make them errors instead. +This does not mean that @emph{all} non-ANSI constructs get warnings +or errors. + +@xref{Warning Options,,Options to Request or Suppress Warnings}, for +more detail on these and related command-line options. + +@node Bugs +@chapter Reporting Bugs +@cindex bugs +@cindex reporting bugs + +Your bug reports play an essential role in making GNU CC reliable. + +When you encounter a problem, the first thing to do is to see if it is +already known. @xref{Trouble}. If it isn't known, then you should +report the problem. + +Reporting a bug may help you by bringing a solution to your problem, or +it may not. (If it does not, look in the service directory; see +@ref{Service}.) In any case, the principal function of a bug report is +to help the entire community by making the next version of GNU CC work +better. Bug reports are your contribution to the maintenance of GNU CC. + +Since the maintainers are very overloaded, we cannot respond to every +bug report. However, if the bug has not been fixed, we are likely to +send you a patch and ask you to tell us whether it works. + +In order for a bug report to serve its purpose, you must include the +information that makes for fixing the bug. + +@menu +* Criteria: Bug Criteria. Have you really found a bug? +* Where: Bug Lists. Where to send your bug report. +* Reporting: Bug Reporting. How to report a bug effectively. +* Patches: Sending Patches. How to send a patch for GNU CC. +* Known: Trouble. Known problems. +* Help: Service. Where to ask for help. +@end menu + +@node Bug Criteria +@section Have You Found a Bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@cindex fatal signal +@cindex core dump +@item +If the compiler gets a fatal signal, for any input whatever, that is a +compiler bug. Reliable compilers never crash. + +@cindex invalid assembly code +@cindex assembly code, invalid +@item +If the compiler produces invalid assembly code, for any input whatever +(except an @code{asm} statement), that is a compiler bug, unless the +compiler reports errors (not just warnings) which would ordinarily +prevent the assembler from being run. + +@cindex undefined behavior +@cindex undefined function value +@cindex increment operators +@item +If the compiler produces valid assembly code that does not correctly +execute the input source code, that is a compiler bug. + +However, you must double-check to make sure, because you may have run +into an incompatibility between GNU C and traditional C +(@pxref{Incompatibilities}). These incompatibilities might be considered +bugs, but they are inescapable consequences of valuable features. + +Or you may have a program whose behavior is undefined, which happened +by chance to give the desired results with another C or C++ compiler. + +For example, in many nonoptimizing compilers, you can write @samp{x;} +at the end of a function instead of @samp{return x;}, with the same +results. But the value of the function is undefined if @code{return} +is omitted; it is not a bug when GNU CC produces different results. + +Problems often result from expressions with two increment operators, +as in @code{f (*p++, *p++)}. Your previous compiler might have +interpreted that expression the way you intended; GNU CC might +interpret it another way. Neither compiler is wrong. The bug is +in your code. + +After you have localized the error to a single source line, it should +be easy to check for these things. If your program is correct and +well defined, you have found a compiler bug. + +@item +If the compiler produces an error message for valid input, that is a +compiler bug. + +@cindex invalid input +@item +If the compiler does not produce an error message for invalid input, +that is a compiler bug. However, you should note that your idea of +``invalid input'' might be my idea of ``an extension'' or ``support +for traditional practice''. + +@item +If you are an experienced user of C or C++ compilers, your suggestions +for improvement of GNU CC or GNU C++ are welcome in any case. +@end itemize + +@node Bug Lists +@section Where to Report Bugs +@cindex bug report mailing lists +@kindex bug-gcc@@prep.ai.mit.edu +Send bug reports for GNU C to @samp{bug-gcc@@prep.ai.mit.edu}. + +@kindex bug-g++@@prep.ai.mit.edu +@kindex bug-libg++@@prep.ai.mit.edu +Send bug reports for GNU C++ to @samp{bug-g++@@prep.ai.mit.edu}. +If your bug involves the C++ class library libg++, send mail to +@samp{bug-lib-g++@@prep.ai.mit.edu}. If you're not sure, you can send +the bug report to both lists. + +@strong{Do not send bug reports to @samp{help-gcc@@prep.ai.mit.edu} or +to the newsgroup @samp{gnu.gcc.help}.} Most users of GNU CC do not want +to receive bug reports. Those that do, have asked to be on +@samp{bug-gcc} and/or @samp{bug-g++}. + +The mailing lists @samp{bug-gcc} and @samp{bug-g++} both have newsgroups +which serve as repeaters: @samp{gnu.gcc.bug} and @samp{gnu.g++.bug}. +Each mailing list and its newsgroup carry exactly the same messages. + +Often people think of posting bug reports to the newsgroup instead of +mailing them. This appears to work, but it has one problem which can be +crucial: a newsgroup posting does not contain a mail path back to the +sender. Thus, if maintainers need more information, they may be unable +to reach you. For this reason, you should always send bug reports by +mail to the proper mailing list. + +As a last resort, send bug reports on paper to: + +@example +GNU Compiler Bugs +Free Software Foundation +59 Temple Place - Suite 330 +Boston, MA 02111-1307, USA +@end example + +@node Bug Reporting +@section How to Report Bugs +@cindex compiler bugs, reporting + +The fundamental principle of reporting bugs usefully is this: +@strong{report all the facts}. If you are not sure whether to state a +fact or leave it out, state it! + +Often people omit facts because they think they know what causes the +problem and they conclude that some details don't matter. Thus, you might +assume that the name of the variable you use in an example does not matter. +Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a +stray memory reference which happens to fetch from the location where that +name is stored in memory; perhaps, if the name were different, the contents +of that location would fool the compiler into doing the right thing despite +the bug. Play it safe and give a specific, complete example. That is the +easiest thing for you to do, and the most helpful. + +Keep in mind that the purpose of a bug report is to enable someone to +fix the bug if it is not known. It isn't very important what happens if +the bug is already known. Therefore, always write your bug reports on +the assumption that the bug is not known. + +Sometimes people give a few sketchy facts and ask, ``Does this ring a +bell?'' This cannot help us fix a bug, so it is basically useless. We +respond by asking for enough details to enable us to investigate. +You might as well expedite matters by sending them to begin with. + +Try to make your bug report self-contained. If we have to ask you for +more information, it is best if you include all the previous information +in your response, as well as the information that was missing. + +Please report each bug in a separate message. This makes it easier for +us to track which bugs have been fixed and to forward your bugs reports +to the appropriate maintainer. + +Do not compress and encode any part of your bug report using programs +such as @file{uuencode}. If you do so it will slow down the processing +of your bug. If you must submit multiple large files, use @file{shar}, +which allows us to read your message without having to run any +decompression programs. + +To enable someone to investigate the bug, you should include all these +things: + +@itemize @bullet +@item +The version of GNU CC. You can get this by running it with the +@samp{-v} option. + +Without this, we won't know whether there is any point in looking for +the bug in the current version of GNU CC. + +@item +A complete input file that will reproduce the bug. If the bug is in the +C preprocessor, send a source file and any header files that it +requires. If the bug is in the compiler proper (@file{cc1}), run your +source file through the C preprocessor by doing @samp{gcc -E +@var{sourcefile} > @var{outfile}}, then include the contents of +@var{outfile} in the bug report. (When you do this, use the same +@samp{-I}, @samp{-D} or @samp{-U} options that you used in actual +compilation.) + +A single statement is not enough of an example. In order to compile it, +it must be embedded in a complete file of compiler input; and the bug +might depend on the details of how this is done. + +Without a real example one can compile, all anyone can do about your bug +report is wish you luck. It would be futile to try to guess how to +provoke the bug. For example, bugs in register allocation and reloading +frequently depend on every little detail of the function they happen in. + +Even if the input file that fails comes from a GNU program, you should +still send the complete test case. Don't ask the GNU CC maintainers to +do the extra work of obtaining the program in question---they are all +overworked as it is. Also, the problem may depend on what is in the +header files on your system; it is unreliable for the GNU CC maintainers +to try the problem with the header files available to them. By sending +CPP output, you can eliminate this source of uncertainty and save us +a certain percentage of wild goose chases. + +@item +The command arguments you gave GNU CC or GNU C++ to compile that example +and observe the bug. For example, did you use @samp{-O}? To guarantee +you won't omit something important, list all the options. + +If we were to try to guess the arguments, we would probably guess wrong +and then we would not encounter the bug. + +@item +The type of machine you are using, and the operating system name and +version number. + +@item +The operands you gave to the @code{configure} command when you installed +the compiler. + +@item +A complete list of any modifications you have made to the compiler +source. (We don't promise to investigate the bug unless it happens in +an unmodified compiler. But if you've made modifications and don't tell +us, then you are sending us on a wild goose chase.) + +Be precise about these changes. A description in English is not +enough---send a context diff for them. + +Adding files of your own (such as a machine description for a machine we +don't support) is a modification of the compiler source. + +@item +Details of any other deviations from the standard procedure for installing +GNU CC. + +@item +A description of what behavior you observe that you believe is +incorrect. For example, ``The compiler gets a fatal signal,'' or, +``The assembler instruction at line 208 in the output is incorrect.'' + +Of course, if the bug is that the compiler gets a fatal signal, then one +can't miss it. But if the bug is incorrect output, the maintainer might +not notice unless it is glaringly wrong. None of us has time to study +all the assembler code from a 50-line C program just on the chance that +one instruction might be wrong. We need @emph{you} to do this part! + +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of the compiler is out of synch, or you have encountered a bug in +the C library on your system. (This has happened!) Your copy might +crash and the copy here would not. If you @i{said} to expect a crash, +then when the compiler here fails to crash, we would know that the bug +was not happening. If you don't say to expect a crash, then we would +not know whether the bug was happening. We would not be able to draw +any conclusion from our observations. + +If the problem is a diagnostic when compiling GNU CC with some other +compiler, say whether it is a warning or an error. + +Often the observed symptom is incorrect output when your program is run. +Sad to say, this is not enough information unless the program is short +and simple. None of us has time to study a large program to figure out +how it would work if compiled correctly, much less which line of it was +compiled wrong. So you will have to do that. Tell us which source line +it is, and what incorrect result happens when that line is executed. A +person who understands the program can find this as easily as finding a +bug in the program itself. + +@item +If you send examples of assembler code output from GNU CC or GNU C++, +please use @samp{-g} when you make them. The debugging information +includes source line numbers which are essential for correlating the +output with the input. + +@item +If you wish to mention something in the GNU CC source, refer to it by +context, not by line number. + +The line numbers in the development sources don't match those in your +sources. Your line numbers would convey no useful information to the +maintainers. + +@item +Additional information from a debugger might enable someone to find a +problem on a machine which he does not have available. However, you +need to think when you collect this information if you want it to have +any chance of being useful. + +@cindex backtrace for bug reports +For example, many people send just a backtrace, but that is never +useful by itself. A simple backtrace with arguments conveys little +about GNU CC because the compiler is largely data-driven; the same +functions are called over and over for different RTL insns, doing +different things depending on the details of the insn. + +Most of the arguments listed in the backtrace are useless because they +are pointers to RTL list structure. The numeric values of the +pointers, which the debugger prints in the backtrace, have no +significance whatever; all that matters is the contents of the objects +they point to (and most of the contents are other such pointers). + +In addition, most compiler passes consist of one or more loops that +scan the RTL insn sequence. The most vital piece of information about +such a loop---which insn it has reached---is usually in a local variable, +not in an argument. + +@findex debug_rtx +What you need to provide in addition to a backtrace are the values of +the local variables for several stack frames up. When a local +variable or an argument is an RTX, first print its value and then use +the GDB command @code{pr} to print the RTL expression that it points +to. (If GDB doesn't run on your machine, use your debugger to call +the function @code{debug_rtx} with the RTX as an argument.) In +general, whenever a variable is a pointer, its value is no use +without the data it points to. +@end itemize + +Here are some things that are not necessary: + +@itemize @bullet +@item +A description of the envelope of the bug. + +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. + +This is often time consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger with +breakpoints, not by pure deduction from a series of examples. You might +as well save your time for something else. + +Of course, if you can find a simpler example to report @emph{instead} of +the original one, that is a convenience. Errors in the output will be +easier to spot, running under the debugger will take less time, etc. +Most GNU CC bugs involve just one function, so the most straightforward +way to simplify an example is to delete all the function definitions +except the one where the bug occurs. Those earlier in the file may be +replaced by external declarations if the crucial function depends on +them. (Exception: inline functions may affect compilation of functions +defined later in the file.) + +However, simplification is not vital; if you don't want to do this, +report the bug anyway and send the entire test case you used. + +@item +In particular, some people insert conditionals @samp{#ifdef BUG} around +a statement which, if removed, makes the bug not happen. These are just +clutter; we won't pay any attention to them anyway. Besides, you should +send us cpp output, and that can't have conditionals. + +@item +A patch for the bug. + +A patch for the bug is useful if it is a good one. But don't omit the +necessary information, such as the test case, on the assumption that a +patch is all we need. We might see problems with your patch and decide +to fix the problem another way, or we might not understand it at all. + +Sometimes with a program as complicated as GNU CC it is very hard to +construct an example that will make the program follow a certain path +through the code. If you don't send the example, we won't be able to +construct one, so we won't be able to verify that the bug is fixed. + +And if we can't understand what bug you are trying to fix, or why your +patch should be an improvement, we won't install it. A test case will +help us to understand. + +@xref{Sending Patches}, for guidelines on how to make it easy for us to +understand and install your patches. + +@item +A guess about what the bug is or what it depends on. + +Such guesses are usually wrong. Even I can't guess right about such +things without first using the debugger to find the facts. + +@item +A core dump file. + +We have no way of examining a core dump for your type of machine +unless we have an identical system---and if we do have one, +we should be able to reproduce the crash ourselves. +@end itemize + +@node Sending Patches,, Bug Reporting, Bugs +@section Sending Patches for GNU CC + +If you would like to write bug fixes or improvements for the GNU C +compiler, that is very helpful. Send suggested fixes to the bug report +mailing list, @code{bug-gcc@@prep.ai.mit.edu}. + +Please follow these guidelines so we can study your patches efficiently. +If you don't follow these guidelines, your information might still be +useful, but using it will take extra work. Maintaining GNU C is a lot +of work in the best of circumstances, and we can't keep up unless you do +your best to help. + +@itemize @bullet +@item +Send an explanation with your changes of what problem they fix or what +improvement they bring about. For a bug fix, just include a copy of the +bug report, and explain why the change fixes the bug. + +(Referring to a bug report is not as good as including it, because then +we will have to look it up, and we have probably already deleted it if +we've already fixed the bug.) + +@item +Always include a proper bug report for the problem you think you have +fixed. We need to convince ourselves that the change is right before +installing it. Even if it is right, we might have trouble judging it if +we don't have a way to reproduce the problem. + +@item +Include all the comments that are appropriate to help people reading the +source in the future understand why this change was needed. + +@item +Don't mix together changes made for different reasons. +Send them @emph{individually}. + +If you make two changes for separate reasons, then we might not want to +install them both. We might want to install just one. If you send them +all jumbled together in a single set of diffs, we have to do extra work +to disentangle them---to figure out which parts of the change serve +which purpose. If we don't have time for this, we might have to ignore +your changes entirely. + +If you send each change as soon as you have written it, with its own +explanation, then the two changes never get tangled up, and we can +consider each one properly without any extra work to disentangle them. + +Ideally, each change you send should be impossible to subdivide into +parts that we might want to consider separately, because each of its +parts gets its motivation from the other parts. + +@item +Send each change as soon as that change is finished. Sometimes people +think they are helping us by accumulating many changes to send them all +together. As explained above, this is absolutely the worst thing you +could do. + +Since you should send each change separately, you might as well send it +right away. That gives us the option of installing it immediately if it +is important. + +@item +Use @samp{diff -c} to make your diffs. Diffs without context are hard +for us to install reliably. More than that, they make it hard for us to +study the diffs to decide whether we want to install them. Unidiff +format is better than contextless diffs, but not as easy to read as +@samp{-c} format. + +If you have GNU diff, use @samp{diff -cp}, which shows the name of the +function that each change occurs in. + +@item +Write the change log entries for your changes. We get lots of changes, +and we don't have time to do all the change log writing ourselves. + +Read the @file{ChangeLog} file to see what sorts of information to put +in, and to learn the style that we use. The purpose of the change log +is to show people where to find what was changed. So you need to be +specific about what functions you changed; in large functions, it's +often helpful to indicate where within the function the change was. + +On the other hand, once you have shown people where to find the change, +you need not explain its purpose. Thus, if you add a new function, all +you need to say about it is that it is new. If you feel that the +purpose needs explaining, it probably does---but the explanation will be +much more useful if you put it in comments in the code. + +If you would like your name to appear in the header line for who made +the change, send us the header line. + +@item +When you write the fix, keep in mind that we can't install a change that +would break other systems. + +People often suggest fixing a problem by changing machine-independent +files such as @file{toplev.c} to do something special that a particular +system needs. Sometimes it is totally obvious that such changes would +break GNU CC for almost all users. We can't possibly make a change like +that. At best it might tell us how to write another patch that would +solve the problem acceptably. + +Sometimes people send fixes that @emph{might} be an improvement in +general---but it is hard to be sure of this. It's hard to install +such changes because we have to study them very carefully. Of course, +a good explanation of the reasoning by which you concluded the change +was correct can help convince us. + +The safest changes are changes to the configuration files for a +particular machine. These are safe because they can't create new bugs +on other machines. + +Please help us keep up with the workload by designing the patch in a +form that is good to install. +@end itemize + +@node Service +@chapter How To Get Help with GNU CC + +If you need help installing, using or changing GNU CC, there are two +ways to find it: + +@itemize @bullet +@item +Send a message to a suitable network mailing list. First try +@code{bug-gcc@@prep.ai.mit.edu}, and if that brings no response, try +@code{help-gcc@@prep.ai.mit.edu}. + +@item +Look in the service directory for someone who might help you for a fee. +The service directory is found in the file named @file{SERVICE} in the +GNU CC distribution. +@end itemize + +@node VMS +@chapter Using GNU CC on VMS + +@c prevent bad page break with this line +Here is how to use GNU CC on VMS. + +@menu +* Include Files and VMS:: Where the preprocessor looks for the include files. +* Global Declarations:: How to do globaldef, globalref and globalvalue with + GNU CC. +* VMS Misc:: Misc information. +@end menu + +@node Include Files and VMS +@section Include Files and VMS + +@cindex include files and VMS +@cindex VMS and include files +@cindex header files and VMS +Due to the differences between the filesystems of Unix and VMS, GNU CC +attempts to translate file names in @samp{#include} into names that VMS +will understand. The basic strategy is to prepend a prefix to the +specification of the include file, convert the whole filename to a VMS +filename, and then try to open the file. GNU CC tries various prefixes +one by one until one of them succeeds: + +@enumerate +@item +The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is +where GNU C header files are traditionally stored. If you wish to store +header files in non-standard locations, then you can assign the logical +@samp{GNU_CC_INCLUDE} to be a search list, where each element of the +list is suitable for use with a rooted logical. + +@item +The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where +VAX-C header files are traditionally stored. + +@item +If the include file specification by itself is a valid VMS filename, the +preprocessor then uses this name with no prefix in an attempt to open +the include file. + +@item +If the file specification is not a valid VMS filename (i.e. does not +contain a device or a directory specifier, and contains a @samp{/} +character), the preprocessor tries to convert it from Unix syntax to +VMS syntax. + +Conversion works like this: the first directory name becomes a device, +and the rest of the directories are converted into VMS-format directory +names. For example, the name @file{X11/foobar.h} is +translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h}, +whichever one can be opened. This strategy allows you to assign a +logical name to point to the actual location of the header files. + +@item +If none of these strategies succeeds, the @samp{#include} fails. +@end enumerate + +Include directives of the form: + +@example +#include foobar +@end example + +@noindent +are a common source of incompatibility between VAX-C and GNU CC. VAX-C +treats this much like a standard @code{#include <foobar.h>} directive. +That is incompatible with the ANSI C behavior implemented by GNU CC: to +expand the name @code{foobar} as a macro. Macro expansion should +eventually yield one of the two standard formats for @code{#include}: + +@example +#include "@var{file}" +#include <@var{file}> +@end example + +If you have this problem, the best solution is to modify the source to +convert the @code{#include} directives to one of the two standard forms. +That will work with either compiler. If you want a quick and dirty fix, +define the file names as macros with the proper expansion, like this: + +@example +#define stdio <stdio.h> +@end example + +@noindent +This will work, as long as the name doesn't conflict with anything else +in the program. + +Another source of incompatibility is that VAX-C assumes that: + +@example +#include "foobar" +@end example + +@noindent +is actually asking for the file @file{foobar.h}. GNU CC does not +make this assumption, and instead takes what you ask for literally; +it tries to read the file @file{foobar}. The best way to avoid this +problem is to always specify the desired file extension in your include +directives. + +GNU CC for VMS is distributed with a set of include files that is +sufficient to compile most general purpose programs. Even though the +GNU CC distribution does not contain header files to define constants +and structures for some VMS system-specific functions, there is no +reason why you cannot use GNU CC with any of these functions. You first +may have to generate or create header files, either by using the public +domain utility @code{UNSDL} (which can be found on a DECUS tape), or by +extracting the relevant modules from one of the system macro libraries, +and using an editor to construct a C header file. + +A @code{#include} file name cannot contain a DECNET node name. The +preprocessor reports an I/O error if you attempt to use a node name, +whether explicitly, or implicitly via a logical name. + +@node Global Declarations +@section Global Declarations and VMS + +@findex GLOBALREF +@findex GLOBALDEF +@findex GLOBALVALUEDEF +@findex GLOBALVALUEREF +GNU CC does not provide the @code{globalref}, @code{globaldef} and +@code{globalvalue} keywords of VAX-C. You can get the same effect with +an obscure feature of GAS, the GNU assembler. (This requires GAS +version 1.39 or later.) The following macros allow you to use this +feature in a fairly natural way: + +@smallexample +#ifdef __GNUC__ +#define GLOBALREF(TYPE,NAME) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) +#define GLOBALDEF(TYPE,NAME,VALUE) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ + = VALUE +#define GLOBALVALUEREF(TYPE,NAME) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) +#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ + = @{VALUE@} +#else +#define GLOBALREF(TYPE,NAME) \ + globalref TYPE NAME +#define GLOBALDEF(TYPE,NAME,VALUE) \ + globaldef TYPE NAME = VALUE +#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + globalvalue TYPE NAME = VALUE +#define GLOBALVALUEREF(TYPE,NAME) \ + globalvalue TYPE NAME +#endif +@end smallexample + +@noindent +(The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the +name is removed by the assembler, after it has modified the attributes +of the symbol). These macros are provided in the VMS binaries +distribution in a header file @file{GNU_HACKS.H}. An example of the +usage is: + +@example +GLOBALREF (int, ijk); +GLOBALDEF (int, jkl, 0); +@end example + +The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used +straightforwardly for arrays, since there is no way to insert the array +dimension into the declaration at the right place. However, you can +declare an array with these macros if you first define a typedef for the +array type, like this: + +@example +typedef int intvector[10]; +GLOBALREF (intvector, foo); +@end example + +Array and structure initializers will also break the macros; you can +define the initializer to be a macro of its own, or you can expand the +@code{GLOBALDEF} macro by hand. You may find a case where you wish to +use the @code{GLOBALDEF} macro with a large array, but you are not +interested in explicitly initializing each element of the array. In +such cases you can use an initializer like: @code{@{0,@}}, which will +initialize the entire array to @code{0}. + +A shortcoming of this implementation is that a variable declared with +@code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For +example, the declaration: + +@example +GLOBALVALUEREF(int, ijk); +@end example + +@noindent +declares the variable @code{ijk} as an array of type @code{int [1]}. +This is done because a globalvalue is actually a constant; its ``value'' +is what the linker would normally consider an address. That is not how +an integer value works in C, but it is how an array works. So treating +the symbol as an array name gives consistent results---with the +exception that the value seems to have the wrong type. @strong{Don't +try to access an element of the array.} It doesn't have any elements. +The array ``address'' may not be the address of actual storage. + +The fact that the symbol is an array may lead to warnings where the +variable is used. Insert type casts to avoid the warnings. Here is an +example; it takes advantage of the ANSI C feature allowing macros that +expand to use the same name as the macro itself. + +@example +GLOBALVALUEREF (int, ss$_normal); +GLOBALVALUEDEF (int, xyzzy,123); +#ifdef __GNUC__ +#define ss$_normal ((int) ss$_normal) +#define xyzzy ((int) xyzzy) +#endif +@end example + +Don't use @code{globaldef} or @code{globalref} with a variable whose +type is an enumeration type; this is not implemented. Instead, make the +variable an integer, and use a @code{globalvaluedef} for each of the +enumeration values. An example of this would be: + +@example +#ifdef __GNUC__ +GLOBALDEF (int, color, 0); +GLOBALVALUEDEF (int, RED, 0); +GLOBALVALUEDEF (int, BLUE, 1); +GLOBALVALUEDEF (int, GREEN, 3); +#else +enum globaldef color @{RED, BLUE, GREEN = 3@}; +#endif +@end example + +@node VMS Misc +@section Other VMS Issues + +@cindex exit status and VMS +@cindex return value of @code{main} +@cindex @code{main} and the exit status +GNU CC automatically arranges for @code{main} to return 1 by default if +you fail to specify an explicit return value. This will be interpreted +by VMS as a status code indicating a normal successful completion. +Version 1 of GNU CC did not provide this default. + +GNU CC on VMS works only with the GNU assembler, GAS. You need version +1.37 or later of GAS in order to produce value debugging information for +the VMS debugger. Use the ordinary VMS linker with the object files +produced by GAS. + +@cindex shared VMS run time system +@cindex @file{VAXCRTL} +Under previous versions of GNU CC, the generated code would occasionally +give strange results when linked to the sharable @file{VAXCRTL} library. +Now this should work. + +A caveat for use of @code{const} global variables: the @code{const} +modifier must be specified in every external declaration of the variable +in all of the source files that use that variable. Otherwise the linker +will issue warnings about conflicting attributes for the variable. Your +program will still work despite the warnings, but the variable will be +placed in writable storage. + +@cindex name augmentation +@cindex case sensitivity and VMS +@cindex VMS and case sensitivity +Although the VMS linker does distinguish between upper and lower case +letters in global symbols, most VMS compilers convert all such symbols +into upper case and most run-time library routines also have upper case +names. To be able to reliably call such routines, GNU CC (by means of +the assembler GAS) converts global symbols into upper case like other +VMS compilers. However, since the usual practice in C is to distinguish +case, GNU CC (via GAS) tries to preserve usual C behavior by augmenting +each name that is not all lower case. This means truncating the name +to at most 23 characters and then adding more characters at the end +which encode the case pattern of those 23. Names which contain at +least one dollar sign are an exception; they are converted directly into +upper case without augmentation. + +Name augmentation yields bad results for programs that use precompiled +libraries (such as Xlib) which were generated by another compiler. You +can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation; +it makes external C functions and variables case-independent as is usual +on VMS. Alternatively, you could write all references to the functions +and variables in such libraries using lower case; this will work on VMS, +but is not portable to other systems. The compiler option @samp{/NAMES} +also provides control over global name handling. + +Function and variable names are handled somewhat differently with GNU +C++. The GNU C++ compiler performs @dfn{name mangling} on function +names, which means that it adds information to the function name to +describe the data types of the arguments that the function takes. One +result of this is that the name of a function can become very long. +Since the VMS linker only recognizes the first 31 characters in a name, +special action is taken to ensure that each function and variable has a +unique name that can be represented in 31 characters. + +If the name (plus a name augmentation, if required) is less than 32 +characters in length, then no special action is performed. If the name +is longer than 31 characters, the assembler (GAS) will generate a +hash string based upon the function name, truncate the function name to +23 characters, and append the hash string to the truncated name. If the +@samp{/VERBOSE} compiler option is used, the assembler will print both +the full and truncated names of each symbol that is truncated. + +The @samp{/NOCASE_HACK} compiler option should not be used when you are +compiling programs that use libg++. libg++ has several instances of +objects (i.e. @code{Filebuf} and @code{filebuf}) which become +indistinguishable in a case-insensitive environment. This leads to +cases where you need to inhibit augmentation selectively (if you were +using libg++ and Xlib in the same program, for example). There is no +special feature for doing this, but you can get the result by defining a +macro for each mixed case symbol for which you wish to inhibit +augmentation. The macro should expand into the lower case equivalent of +itself. For example: + +@example +#define StuDlyCapS studlycaps +@end example + +These macro definitions can be placed in a header file to minimize the +number of changes to your source code. +@end ifset + +@ifset INTERNALS +@node Portability +@chapter GNU CC and Portability +@cindex portability +@cindex GNU CC and portability + +The main goal of GNU CC was to make a good, fast compiler for machines in +the class that the GNU system aims to run on: 32-bit machines that address +8-bit bytes and have several general registers. Elegance, theoretical +power and simplicity are only secondary. + +GNU CC gets most of the information about the target machine from a machine +description which gives an algebraic formula for each of the machine's +instructions. This is a very clean way to describe the target. But when +the compiler needs information that is difficult to express in this +fashion, I have not hesitated to define an ad-hoc parameter to the machine +description. The purpose of portability is to reduce the total work needed +on the compiler; it was not of interest for its own sake. + +@cindex endianness +@cindex autoincrement addressing, availability +@findex abort +GNU CC does not contain machine dependent code, but it does contain code +that depends on machine parameters such as endianness (whether the most +significant byte has the highest or lowest address of the bytes in a word) +and the availability of autoincrement addressing. In the RTL-generation +pass, it is often necessary to have multiple strategies for generating code +for a particular kind of syntax tree, strategies that are usable for different +combinations of parameters. Often I have not tried to address all possible +cases, but only the common ones or only the ones that I have encountered. +As a result, a new target may require additional strategies. You will know +if this happens because the compiler will call @code{abort}. Fortunately, +the new strategies can be added in a machine-independent fashion, and will +affect only the target machines that need them. +@end ifset + +@ifset INTERNALS +@node Interface +@chapter Interfacing to GNU CC Output +@cindex interfacing to GNU CC output +@cindex run-time conventions +@cindex function call conventions +@cindex conventions, run-time + +GNU CC is normally configured to use the same function calling convention +normally in use on the target system. This is done with the +machine-description macros described (@pxref{Target Macros}). + +@cindex unions, returning +@cindex structures, returning +@cindex returning structures and unions +However, returning of structure and union values is done differently on +some target machines. As a result, functions compiled with PCC +returning such types cannot be called from code compiled with GNU CC, +and vice versa. This does not cause trouble often because few Unix +library routines return structures or unions. + +GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes +long in the same registers used for @code{int} or @code{double} return +values. (GNU CC typically allocates variables of such types in +registers also.) Structures and unions of other sizes are returned by +storing them into an address passed by the caller (usually in a +register). The machine-description macros @code{STRUCT_VALUE} and +@code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address. + +By contrast, PCC on most target machines returns structures and unions +of any size by copying the data into an area of static storage, and then +returning the address of that storage as if it were a pointer value. +The caller must copy the data from that memory area to the place where +the value is wanted. This is slower than the method used by GNU CC, and +fails to be reentrant. + +On some target machines, such as RISC machines and the 80386, the +standard system convention is to pass to the subroutine the address of +where to return the value. On these machines, GNU CC has been +configured to be compatible with the standard compiler, when this method +is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes. + +@cindex argument passing +@cindex passing arguments +GNU CC uses the system's standard convention for passing arguments. On +some machines, the first few arguments are passed in registers; in +others, all are passed on the stack. It would be possible to use +registers for argument passing on any machine, and this would probably +result in a significant speedup. But the result would be complete +incompatibility with code that follows the standard convention. So this +change is practical only if you are switching to GNU CC as the sole C +compiler for the system. We may implement register argument passing on +certain machines once we have a complete GNU system so that we can +compile the libraries with GNU CC. + +On some machines (particularly the Sparc), certain types of arguments +are passed ``by invisible reference''. This means that the value is +stored in memory, and the address of the memory location is passed to +the subroutine. + +@cindex @code{longjmp} and automatic variables +If you use @code{longjmp}, beware of automatic variables. ANSI C says that +automatic variables that are not declared @code{volatile} have undefined +values after a @code{longjmp}. And this is all GNU CC promises to do, +because it is very difficult to restore register variables correctly, and +one of GNU CC's features is that it can put variables in registers without +your asking it to. + +If you want a variable to be unaltered by @code{longjmp}, and you don't +want to write @code{volatile} because old C compilers don't accept it, +just take the address of the variable. If a variable's address is ever +taken, even if just to compute it and ignore it, then the variable cannot +go in a register: + +@example +@{ + int careful; + &careful; + @dots{} +@} +@end example + +@cindex arithmetic libraries +@cindex math libraries +Code compiled with GNU CC may call certain library routines. Most of +them handle arithmetic for which there are no instructions. This +includes multiply and divide on some machines, and floating point +operations on any machine for which floating point support is disabled +with @samp{-msoft-float}. Some standard parts of the C library, such as +@code{bcopy} or @code{memcpy}, are also called automatically. The usual +function call interface is used for calling the library routines. + +These library routines should be defined in the library @file{libgcc.a}, +which GNU CC automatically searches whenever it links a program. On +machines that have multiply and divide instructions, if hardware +floating point is in use, normally @file{libgcc.a} is not needed, but it +is searched just in case. + +Each arithmetic function is defined in @file{libgcc1.c} to use the +corresponding C arithmetic operator. As long as the file is compiled +with another C compiler, which supports all the C arithmetic operators, +this file will work portably. However, @file{libgcc1.c} does not work if +compiled with GNU CC, because each arithmetic function would compile +into a call to itself! +@end ifset + +@ifset INTERNALS +@node Passes +@chapter Passes and Files of the Compiler +@cindex passes and files of the compiler +@cindex files and passes of the compiler +@cindex compiler passes and files + +@cindex top level of compiler +The overall control structure of the compiler is in @file{toplev.c}. This +file is responsible for initialization, decoding arguments, opening and +closing files, and sequencing the passes. + +@cindex parsing pass +The parsing pass is invoked only once, to parse the entire input. The RTL +intermediate code for a function is generated as the function is parsed, a +statement at a time. Each statement is read in as a syntax tree and then +converted to RTL; then the storage for the tree for the statement is +reclaimed. Storage for types (and the expressions for their sizes), +declarations, and a representation of the binding contours and how they nest, +remain until the function is finished being compiled; these are all needed +to output the debugging information. + +@findex rest_of_compilation +@findex rest_of_decl_compilation +Each time the parsing pass reads a complete function definition or +top-level declaration, it calls either the function +@code{rest_of_compilation}, or the function +@code{rest_of_decl_compilation} in @file{toplev.c}, which are +responsible for all further processing necessary, ending with output of +the assembler language. All other compiler passes run, in sequence, +within @code{rest_of_compilation}. When that function returns from +compiling a function definition, the storage used for that function +definition's compilation is entirely freed, unless it is an inline +function +@ifset USING +(@pxref{Inline,,An Inline Function is As Fast As a Macro}). +@end ifset +@ifclear USING +(@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}). +@end ifclear + +Here is a list of all the passes of the compiler and their source files. +Also included is a description of where debugging dumps can be requested +with @samp{-d} options. + +@itemize @bullet +@item +Parsing. This pass reads the entire text of a function definition, +constructing partial syntax trees. This and RTL generation are no longer +truly separate passes (formerly they were), but it is easier to think +of them as separate. + +The tree representation does not entirely follow C syntax, because it is +intended to support other languages as well. + +Language-specific data type analysis is also done in this pass, and every +tree node that represents an expression has a data type attached. +Variables are represented as declaration nodes. + +@cindex constant folding +@cindex arithmetic simplifications +@cindex simplifications, arithmetic +Constant folding and some arithmetic simplifications are also done +during this pass. + +The language-independent source files for parsing are +@file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}. +There are also header files @file{tree.h} and @file{tree.def} +which define the format of the tree representation.@refill + +@c Avoiding overfull is tricky here. +The source files to parse C are +@file{c-parse.in}, +@file{c-decl.c}, +@file{c-typeck.c}, +@file{c-aux-info.c}, +@file{c-convert.c}, +and @file{c-lang.c} +along with header files +@file{c-lex.h}, and +@file{c-tree.h}. + +The source files for parsing C++ are @file{cp-parse.y}, +@file{cp-class.c},@* +@file{cp-cvt.c}, @file{cp-decl.c}, @file{cp-decl2.c}, +@file{cp-dem.c}, @file{cp-except.c},@* +@file{cp-expr.c}, @file{cp-init.c}, @file{cp-lex.c}, +@file{cp-method.c}, @file{cp-ptree.c},@* +@file{cp-search.c}, @file{cp-tree.c}, @file{cp-type2.c}, and +@file{cp-typeck.c}, along with header files @file{cp-tree.def}, +@file{cp-tree.h}, and @file{cp-decl.h}. + +The special source files for parsing Objective C are +@file{objc-parse.y}, @file{objc-actions.c}, @file{objc-tree.def}, and +@file{objc-actions.h}. Certain C-specific files are used for this as +well. + +The file @file{c-common.c} is also used for all of the above languages. + +@cindex RTL generation +@item +RTL generation. This is the conversion of syntax tree into RTL code. +It is actually done statement-by-statement during parsing, but for +most purposes it can be thought of as a separate pass. + +@cindex target-parameter-dependent code +This is where the bulk of target-parameter-dependent code is found, +since often it is necessary for strategies to apply only when certain +standard kinds of instructions are available. The purpose of named +instruction patterns is to provide this information to the RTL +generation pass. + +@cindex tail recursion optimization +Optimization is done in this pass for @code{if}-conditions that are +comparisons, boolean operations or conditional expressions. Tail +recursion is detected at this time also. Decisions are made about how +best to arrange loops and how to output @code{switch} statements. + +@c Avoiding overfull is tricky here. +The source files for RTL generation include +@file{stmt.c}, +@file{calls.c}, +@file{expr.c}, +@file{explow.c}, +@file{expmed.c}, +@file{function.c}, +@file{optabs.c} +and @file{emit-rtl.c}. +Also, the file +@file{insn-emit.c}, generated from the machine description by the +program @code{genemit}, is used in this pass. The header file +@file{expr.h} is used for communication within this pass.@refill + +@findex genflags +@findex gencodes +The header files @file{insn-flags.h} and @file{insn-codes.h}, +generated from the machine description by the programs @code{genflags} +and @code{gencodes}, tell this pass which standard names are available +for use and which patterns correspond to them.@refill + +Aside from debugging information output, none of the following passes +refers to the tree structure representation of the function (only +part of which is saved). + +@cindex inline, automatic +The decision of whether the function can and should be expanded inline +in its subsequent callers is made at the end of rtl generation. The +function must meet certain criteria, currently related to the size of +the function and the types and number of parameters it has. Note that +this function may contain loops, recursive calls to itself +(tail-recursive functions can be inlined!), gotos, in short, all +constructs supported by GNU CC. The file @file{integrate.c} contains +the code to save a function's rtl for later inlining and to inline that +rtl when the function is called. The header file @file{integrate.h} +is also used for this purpose. + +The option @samp{-dr} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.rtl} to +the input file name. + +@cindex jump optimization +@cindex unreachable code +@cindex dead code +@item +Jump optimization. This pass simplifies jumps to the following +instruction, jumps across jumps, and jumps to jumps. It deletes +unreferenced labels and unreachable code, except that unreachable code +that contains a loop is not recognized as unreachable in this pass. +(Such loops are deleted later in the basic block analysis.) It also +converts some code originally written with jumps into sequences of +instructions that directly set values from the results of comparisons, +if the machine has such instructions. + +Jump optimization is performed two or three times. The first time is +immediately following RTL generation. The second time is after CSE, +but only if CSE says repeated jump optimization is needed. The +last time is right before the final pass. That time, cross-jumping +and deletion of no-op move instructions are done together with the +optimizations described above. + +The source file of this pass is @file{jump.c}. + +The option @samp{-dj} causes a debugging dump of the RTL code after +this pass is run for the first time. This dump file's name is made by +appending @samp{.jump} to the input file name. + +@cindex register use analysis +@item +Register scan. This pass finds the first and last use of each +register, as a guide for common subexpression elimination. Its source +is in @file{regclass.c}. + +@cindex jump threading +@item +Jump threading. This pass detects a condition jump that branches to an +identical or inverse test. Such jumps can be @samp{threaded} through +the second conditional test. The source code for this pass is in +@file{jump.c}. This optimization is only performed if +@samp{-fthread-jumps} is enabled. + +@cindex common subexpression elimination +@cindex constant propagation +@item +Common subexpression elimination. This pass also does constant +propagation. Its source file is @file{cse.c}. If constant +propagation causes conditional jumps to become unconditional or to +become no-ops, jump optimization is run again when CSE is finished. + +The option @samp{-ds} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.cse} to +the input file name. + +@cindex loop optimization +@cindex code motion +@cindex strength-reduction +@item +Loop optimization. This pass moves constant expressions out of loops, +and optionally does strength-reduction and loop unrolling as well. +Its source files are @file{loop.c} and @file{unroll.c}, plus the header +@file{loop.h} used for communication between them. Loop unrolling uses +some functions in @file{integrate.c} and the header @file{integrate.h}. + +The option @samp{-dL} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.loop} to +the input file name. + +@item +If @samp{-frerun-cse-after-loop} was enabled, a second common +subexpression elimination pass is performed after the loop optimization +pass. Jump threading is also done again at this time if it was specified. + +The option @samp{-dt} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.cse2} to +the input file name. + +@cindex register allocation, stupid +@cindex stupid register allocation +@item +Stupid register allocation is performed at this point in a +nonoptimizing compilation. It does a little data flow analysis as +well. When stupid register allocation is in use, the next pass +executed is the reloading pass; the others in between are skipped. +The source file is @file{stupid.c}. + +@cindex data flow analysis +@cindex analysis, data flow +@cindex basic blocks +@item +Data flow analysis (@file{flow.c}). This pass divides the program +into basic blocks (and in the process deletes unreachable loops); then +it computes which pseudo-registers are live at each point in the +program, and makes the first instruction that uses a value point at +the instruction that computed the value. + +@cindex autoincrement/decrement analysis +This pass also deletes computations whose results are never used, and +combines memory references with add or subtract instructions to make +autoincrement or autodecrement addressing. + +The option @samp{-df} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.flow} to +the input file name. If stupid register allocation is in use, this +dump file reflects the full results of such allocation. + +@cindex instruction combination +@item +Instruction combination (@file{combine.c}). This pass attempts to +combine groups of two or three instructions that are related by data +flow into single instructions. It combines the RTL expressions for +the instructions by substitution, simplifies the result using algebra, +and then attempts to match the result against the machine description. + +The option @samp{-dc} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.combine} +to the input file name. + +@cindex instruction scheduling +@cindex scheduling, instruction +@item +Instruction scheduling (@file{sched.c}). This pass looks for +instructions whose output will not be available by the time that it is +used in subsequent instructions. (Memory loads and floating point +instructions often have this behavior on RISC machines). It re-orders +instructions within a basic block to try to separate the definition and +use of items that otherwise would cause pipeline stalls. + +Instruction scheduling is performed twice. The first time is immediately +after instruction combination and the second is immediately after reload. + +The option @samp{-dS} causes a debugging dump of the RTL code after this +pass is run for the first time. The dump file's name is made by +appending @samp{.sched} to the input file name. + +@cindex register class preference pass +@item +Register class preferencing. The RTL code is scanned to find out +which register class is best for each pseudo register. The source +file is @file{regclass.c}. + +@cindex register allocation +@cindex local register allocation +@item +Local register allocation (@file{local-alloc.c}). This pass allocates +hard registers to pseudo registers that are used only within one basic +block. Because the basic block is linear, it can use fast and +powerful techniques to do a very good job. + +The option @samp{-dl} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.lreg} to +the input file name. + +@cindex global register allocation +@item +Global register allocation (@file{global.c}). This pass +allocates hard registers for the remaining pseudo registers (those +whose life spans are not contained in one basic block). + +@cindex reloading +@item +Reloading. This pass renumbers pseudo registers with the hardware +registers numbers they were allocated. Pseudo registers that did not +get hard registers are replaced with stack slots. Then it finds +instructions that are invalid because a value has failed to end up in +a register, or has ended up in a register of the wrong kind. It fixes +up these instructions by reloading the problematical values +temporarily into registers. Additional instructions are generated to +do the copying. + +The reload pass also optionally eliminates the frame pointer and inserts +instructions to save and restore call-clobbered registers around calls. + +Source files are @file{reload.c} and @file{reload1.c}, plus the header +@file{reload.h} used for communication between them. + +The option @samp{-dg} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.greg} to +the input file name. + +@cindex instruction scheduling +@cindex scheduling, instruction +@item +Instruction scheduling is repeated here to try to avoid pipeline stalls +due to memory loads generated for spilled pseudo registers. + +The option @samp{-dR} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.sched2} +to the input file name. + +@cindex cross-jumping +@cindex no-op move instructions +@item +Jump optimization is repeated, this time including cross-jumping +and deletion of no-op move instructions. + +The option @samp{-dJ} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.jump2} +to the input file name. + +@cindex delayed branch scheduling +@cindex scheduling, delayed branch +@item +Delayed branch scheduling. This optional pass attempts to find +instructions that can go into the delay slots of other instructions, +usually jumps and calls. The source file name is @file{reorg.c}. + +The option @samp{-dd} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.dbr} +to the input file name. + +@cindex register-to-stack conversion +@item +Conversion from usage of some hard registers to usage of a register +stack may be done at this point. Currently, this is supported only +for the floating-point registers of the Intel 80387 coprocessor. The +source file name is @file{reg-stack.c}. + +The options @samp{-dk} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.stack} +to the input file name. + +@cindex final pass +@cindex peephole optimization +@item +Final. This pass outputs the assembler code for the function. It is +also responsible for identifying spurious test and compare +instructions. Machine-specific peephole optimizations are performed +at the same time. The function entry and exit sequences are generated +directly as assembler code in this pass; they never exist as RTL. + +The source files are @file{final.c} plus @file{insn-output.c}; the +latter is generated automatically from the machine description by the +tool @file{genoutput}. The header file @file{conditions.h} is used +for communication between these files. + +@cindex debugging information generation +@item +Debugging information output. This is run after final because it must +output the stack slot offsets for pseudo registers that did not get +hard registers. Source files are @file{dbxout.c} for DBX symbol table +format, @file{sdbout.c} for SDB symbol table format, and +@file{dwarfout.c} for DWARF symbol table format. +@end itemize + +Some additional files are used by all or many passes: + +@itemize @bullet +@item +Every pass uses @file{machmode.def} and @file{machmode.h} which define +the machine modes. + +@item +Several passes use @file{real.h}, which defines the default +representation of floating point constants and how to operate on them. + +@item +All the passes that work with RTL use the header files @file{rtl.h} +and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools +@code{gen*} also use these files to read and work with the machine +description RTL. + +@findex genconfig +@item +Several passes refer to the header file @file{insn-config.h} which +contains a few parameters (C macro definitions) generated +automatically from the machine description RTL by the tool +@code{genconfig}. + +@cindex instruction recognizer +@item +Several passes use the instruction recognizer, which consists of +@file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c} +and @file{insn-extract.c} that are generated automatically from the +machine description by the tools @file{genrecog} and +@file{genextract}.@refill + +@item +Several passes use the header files @file{regs.h} which defines the +information recorded about pseudo register usage, and @file{basic-block.h} +which defines the information recorded about basic blocks. + +@item +@file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector +with a bit for each hard register, and some macros to manipulate it. +This type is just @code{int} if the machine has few enough hard registers; +otherwise it is an array of @code{int} and some of the macros expand +into loops. + +@item +Several passes use instruction attributes. A definition of the +attributes defined for a particular machine is in file +@file{insn-attr.h}, which is generated from the machine description by +the program @file{genattr}. The file @file{insn-attrtab.c} contains +subroutines to obtain the attribute values for insns. It is generated +from the machine description by the program @file{genattrtab}.@refill +@end itemize +@end ifset + +@ifset INTERNALS +@include rtl.texi +@include md.texi +@include tm.texi +@end ifset + +@ifset INTERNALS +@node Config +@chapter The Configuration File +@cindex configuration file +@cindex @file{xm-@var{machine}.h} + +The configuration file @file{xm-@var{machine}.h} contains macro +definitions that describe the machine and system on which the compiler +is running, unlike the definitions in @file{@var{machine}.h}, which +describe the machine for which the compiler is producing output. Most +of the values in @file{xm-@var{machine}.h} are actually the same on all +machines that GNU CC runs on, so large parts of all configuration files +are identical. But there are some macros that vary: + +@table @code +@findex USG +@item USG +Define this macro if the host system is System V. + +@findex VMS +@item VMS +Define this macro if the host system is VMS. + +@findex FATAL_EXIT_CODE +@item FATAL_EXIT_CODE +A C expression for the status code to be returned when the compiler +exits after serious errors. + +@findex SUCCESS_EXIT_CODE +@item SUCCESS_EXIT_CODE +A C expression for the status code to be returned when the compiler +exits without serious errors. + +@findex HOST_WORDS_BIG_ENDIAN +@item HOST_WORDS_BIG_ENDIAN +Defined if the host machine stores words of multi-word values in +big-endian order. (GNU CC does not depend on the host byte ordering +within a word.) + +@findex HOST_FLOAT_WORDS_BIG_ENDIAN +@item HOST_FLOAT_WORDS_BIG_ENDIAN +Define this macro to be 1 if the host machine stores @code{DFmode}, +@code{XFmode} or @code{TFmode} floating point numbers in memory with the +word containing the sign bit at the lowest address; otherwise, define it +to be zero. + +This macro need not be defined if the ordering is the same as for +multi-word integers. + +@findex HOST_FLOAT_FORMAT +@item HOST_FLOAT_FORMAT +A numeric code distinguishing the floating point format for the host +machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the +alternatives and default. + +@findex HOST_BITS_PER_CHAR +@item HOST_BITS_PER_CHAR +A C expression for the number of bits in @code{char} on the host +machine. + +@findex HOST_BITS_PER_SHORT +@item HOST_BITS_PER_SHORT +A C expression for the number of bits in @code{short} on the host +machine. + +@findex HOST_BITS_PER_INT +@item HOST_BITS_PER_INT +A C expression for the number of bits in @code{int} on the host +machine. + +@findex HOST_BITS_PER_LONG +@item HOST_BITS_PER_LONG +A C expression for the number of bits in @code{long} on the host +machine. + +@findex ONLY_INT_FIELDS +@item ONLY_INT_FIELDS +Define this macro to indicate that the host compiler only supports +@code{int} bit fields, rather than other integral types, including +@code{enum}, as do most C compilers. + +@findex OBSTACK_CHUNK_SIZE +@item OBSTACK_CHUNK_SIZE +A C expression for the size of ordinary obstack chunks. +If you don't define this, a usually-reasonable default is used. + +@findex OBSTACK_CHUNK_ALLOC +@item OBSTACK_CHUNK_ALLOC +The function used to allocate obstack chunks. +If you don't define this, @code{xmalloc} is used. + +@findex OBSTACK_CHUNK_FREE +@item OBSTACK_CHUNK_FREE +The function used to free obstack chunks. +If you don't define this, @code{free} is used. + +@findex USE_C_ALLOCA +@item USE_C_ALLOCA +Define this macro to indicate that the compiler is running with the +@code{alloca} implemented in C. This version of @code{alloca} can be +found in the file @file{alloca.c}; to use it, you must also alter the +@file{Makefile} variable @code{ALLOCA}. (This is done automatically +for the systems on which we know it is needed.) + +If you do define this macro, you should probably do it as follows: + +@example +#ifndef __GNUC__ +#define USE_C_ALLOCA +#else +#define alloca __builtin_alloca +#endif +@end example + +@noindent +so that when the compiler is compiled with GNU CC it uses the more +efficient built-in @code{alloca} function. + +@item FUNCTION_CONVERSION_BUG +@findex FUNCTION_CONVERSION_BUG +Define this macro to indicate that the host compiler does not properly +handle converting a function value to a pointer-to-function when it is +used in an expression. + +@findex HAVE_VPRINTF +@findex vprintf +@item HAVE_VPRINTF +Define this if the library function @code{vprintf} is available on your +system. + +@findex MULTIBYTE_CHARS +@item MULTIBYTE_CHARS +Define this macro to enable support for multibyte characters in the +input to GNU CC. This requires that the host system support the ANSI C +library functions for converting multibyte characters to wide +characters. + +@findex HAVE_PUTENV +@findex putenv +@item HAVE_PUTENV +Define this if the library function @code{putenv} is available on your +system. + +@findex POSIX +@item POSIX +Define this if your system is POSIX.1 compliant. + +@findex NO_SYS_SIGLIST +@item NO_SYS_SIGLIST +Define this if your system @emph{does not} provide the variable +@code{sys_siglist}. + +@findex DONT_DECLARE_SYS_SIGLIST +@item DONT_DECLARE_SYS_SIGLIST +Define this if your system has the variable @code{sys_siglist}, and +there is already a declaration of it in the system header files. + +@findex USE_PROTOTYPES +@item USE_PROTOTYPES +Define this to be 1 if you know that the host compiler supports +prototypes, even if it doesn't define __STDC__, or define +it to be 0 if you do not want any prototypes used in compiling +GNU CC. If @samp{USE_PROTOTYPES} is not defined, it will be +determined automatically whether your compiler supports +prototypes by checking if @samp{__STDC__} is defined. + +@findex NO_MD_PROTOTYPES +@item NO_MD_PROTOTYPES +Define this if you wish suppression of prototypes generated from +the machine description file, but to use other prototypes within +GNU CC. If @samp{USE_PROTOTYPES} is defined to be 0, or the +host compiler does not support prototypes, this macro has no +effect. + +@findex MD_CALL_PROTOTYPES +@item MD_CALL_PROTOTYPES +Define this if you wish to generate prototypes for the +@code{gen_call} or @code{gen_call_value} functions generated from +the machine description file. If @samp{USE_PROTOTYPES} is +defined to be 0, or the host compiler does not support +prototypes, or @samp{NO_MD_PROTOTYPES} is defined, this macro has +no effect. As soon as all of the machine descriptions are +modified to have the appropriate number of arguments, this macro +will be removed. + +@vindex sys_siglist +Some systems do provide this variable, but with a different name such +as @code{_sys_siglist}. On these systems, you can define +@code{sys_siglist} as a macro which expands into the name actually +provided. + +@findex NO_STAB_H +@item NO_STAB_H +Define this if your system does not have the include file +@file{stab.h}. If @samp{USG} is defined, @samp{NO_STAB_H} is +assumed. + +@findex PATH_SEPARATOR +@item PATH_SEPARATOR +Define this macro to be a C character constant representing the +character used to separate components in paths. The default value is. +the colon character + +@findex DIR_SEPARATOR +@item DIR_SEPARATOR +If your system uses some character other than slash to separate +directory names within a file specification, define this macro to be a C +character constant specifying that character. When GNU CC displays file +names, the character you specify will be used. GNU CC will test for +both slash and the character you specify when parsing filenames. + +@findex OBJECT_SUFFIX +@item OBJECT_SUFFIX +Define this macro to be a C string representing the suffix for object +files on your machine. If you do not define this macro, GNU CC will use +@samp{.o} as the suffix for object files. + +@findex EXECUTABLE_SUFFIX +@item EXECUTABLE_SUFFIX +Define this macro to be a C string representing the suffix for executable +files on your machine. If you do not define this macro, GNU CC will use +the null string as the suffix for object files. + +@findex COLLECT_EXPORT_LIST +@item COLLECT_EXPORT_LIST +If defined, @code{collect2} will scan the individual object files +specified on its command line and create an export list for the linker. +Define this macro for systems like AIX, where the linker discards +object files that are not referenced from @code{main} and uses export +lists. +@end table + +@findex bzero +@findex bcmp +In addition, configuration files for system V define @code{bcopy}, +@code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca} +as a macro when compiled with GNU CC, in order to take advantage of the +benefit of GNU CC's built-in @code{alloca}. + +@node Fragments +@chapter Makefile Fragments +@cindex makefile fragment + +When you configure GNU CC using the @file{configure} script +(@pxref{Installation}), it will construct the file @file{Makefile} from +the template file @file{Makefile.in}. When it does this, it will +incorporate makefile fragment files from the @file{config} directory, +named @file{t-@var{target}} and @file{x-@var{host}}. If these files do +not exist, it means nothing needs to be added for a given target or +host. + +@menu +* Target Fragment:: Writing the @file{t-@var{target}} file. +* Host Fragment:: Writing the @file{x-@var{host}} file. +@end menu + +@node Target Fragment +@section The Target Makefile Fragment +@cindex target makefile fragment +@cindex @file{t-@var{target}} + +The target makefile fragment, @file{t-@var{target}}, defines special +target dependent variables and targets used in the @file{Makefile}: + +@table @code +@findex LIBGCC1 +@item LIBGCC1 +The rule to use to build @file{libgcc1.a}. +If your target does not need to use the functions in @file{libgcc1.a}, +set this to empty. +@xref{Interface}. + +@findex CROSS_LIBGCC1 +@item CROSS_LIBGCC1 +The rule to use to build @file{libgcc1.a} when building a cross +compiler. If your target does not need to use the functions in +@file{libgcc1.a}, set this to empty. @xref{Cross Runtime}. + +@findex LIBGCC2_CFLAGS +@item LIBGCC2_CFLAGS +Compiler flags to use when compiling @file{libgcc2.c}. + +@findex LIB2FUNCS_EXTRA +@item LIB2FUNCS_EXTRA +A list of source file names to be compiled or assembled and inserted +into @file{libgcc.a}. + +@findex CRTSTUFF_T_CFLAGS +@item CRTSTUFF_T_CFLAGS +Special flags used when compiling @file{crtstuff.c}. +@xref{Initialization}. + +@findex MULTILIB_OPTIONS +@item MULTILIB_OPTIONS +For some targets, invoking GNU CC in different ways produces objects +that can not be linked together. For example, for some targets GNU CC +produces both big and little endian code. For these targets, you must +arrange for multiple versions of @file{libgcc.a} to be compiled, one for +each set of incompatible options. When GNU CC invokes the linker, it +arranges to link in the right version of @file{libgcc.a}, based on +the command line options used. + +The @code{MULTILIB_OPTIONS} macro lists the set of options for which +special versions of @file{libgcc.a} must be built. Write options that +are mutually incompatible side by side, separated by a slash. Write +options that may be used together separated by a space. The build +procedure will build all combinations of compatible options. + +For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020 +msoft-float}, @file{Makefile} will build special versions of +@file{libgcc.a} using the options @samp{-m68000}, @samp{-m68020}, +@samp{-msoft-float}, @samp{-m68000 -msoft-float}, and @samp{-m68020 +-msoft-float}. + +@findex MULTILIB_DIRNAMES +@item MULTILIB_DIRNAMES +If @code{MULTILIB_OPTIONS} is used, this variable specifies the +directory names that should be used to hold the various libraries. +Write one element in @code{MULTILIB_DIRNAMES} for each element in +@code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the +default value will be @code{MULTILIB_OPTIONS}, with all slashes treated +as spaces. + +For example, if @code{MULTILIB_OPTIONS} is @samp{m68000/m68020 +msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is +@samp{m68000 m68020 msoft-float}. You may specify a different value if +you desire a different set of directory names. + +@findex MULTILIB_MATCHES +@item MULTILIB_MATCHES +Sometimes the same option may be written in two different ways. If an +option is listed in @code{MULTILIB_OPTIONS}, GNU CC needs to know about +any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of +items of the form @samp{option=option} to describe all relevant +synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}. +@end table + +@node Host Fragment +@section The Host Makefile Fragment +@cindex host makefile fragment +@cindex @file{x-@var{host}} + +The host makefile fragment, @file{x-@var{host}}, defines special host +dependent variables and targets used in the @file{Makefile}: + +@table @code +@findex CC +@item CC +The compiler to use when building the first stage. + +@findex CLIB +@item CLIB +Additional host libraries to link with. + +@findex OLDCC +@item OLDCC +The compiler to use when building @file{libgcc1.a} for a native +compilation. + +@findex OLDAR +@item OLDAR +The version of @code{ar} to use when building @file{libgcc1.a} for a native +compilation. + +@findex INSTALL +@item INSTALL +The install program to use. +@end table + +@node Index +@unnumbered Index +@end ifset + +@ifclear INTERNALS +@node Index +@unnumbered Index +@end ifclear + +@printindex cp +@summarycontents +@contents +@bye |
