Return to gcc.texi CVS log

Up to [Apple XNU] / GNUtools / cc

Annotation of GNUtools/cc/gcc.texi, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.