Return to gcc.texi CVS log

Up to [GCC 2.x] / gcc

Annotation of gcc/gcc.texi, revision 1.1

1.1     ! root        1: \input texinfo  @c -*-texinfo-*-
        !             2: @setfilename gcc.info
        !             3: @c @setfilename usegcc.info
        !             4: @c To produce the full manual, use the "gcc.info" setfilename, and
        !             5: @c make sure the following does NOT begin with '@c' (and the @clear line DOES)
        !             6: @set INTERNALS
        !             7: @c To produce a user-only manual, use the "usegcc.info" setfilename, and
        !             8: @c make sure the following does NOT begin with '@c':
        !             9: @c @clear INTERNALS
        !            10: 
        !            11: @ifset INTERNALS
        !            12: @settitle Using and Porting GNU CC
        !            13: @end ifset
        !            14: @ifclear INTERNALS
        !            15: @settitle Using GNU CC
        !            16: @end ifclear
        !            17: 
        !            18: @syncodeindex fn cp
        !            19: 
        !            20: @ifinfo
        !            21: This file documents the use
        !            22: @ifset INTERNALS
        !            23: and the internals
        !            24: @end ifset
        !            25: of the GNU compiler.
        !            26: 
        !            27: Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
        !            28: 
        !            29: Permission is granted to make and distribute verbatim copies of
        !            30: this manual provided the copyright notice and this permission notice
        !            31: are preserved on all copies.
        !            32: 
        !            33: @ignore
        !            34: Permission is granted to process this file through Tex and print the
        !            35: results, provided the printed document carries copying permission
        !            36: notice identical to this one except for the removal of this paragraph
        !            37: (this paragraph not being relevant to the printed manual).
        !            38: 
        !            39: @end ignore
        !            40: Permission is granted to copy and distribute modified versions of this
        !            41: manual under the conditions for verbatim copying, provided also that the
        !            42: section entitled ``GNU General Public License'' is included exactly as
        !            43: in the original, and provided that the entire resulting derived work is
        !            44: distributed under the terms of a permission notice identical to this one.
        !            45: 
        !            46: Permission is granted to copy and distribute translations of this manual
        !            47: into another language, under the above conditions for modified versions,
        !            48: except that the section entitled ``GNU General Public License'' and
        !            49: this permission notice may be included in translations approved by the
        !            50: Free Software Foundation instead of in the original English.
        !            51: @end ifinfo
        !            52: 
        !            53: @setchapternewpage odd
        !            54: 
        !            55: @titlepage
        !            56: @ifset INTERNALS
        !            57: @center @titlefont{Using and Porting GNU CC}
        !            58: @end ifset
        !            59: @ifclear INTERNALS
        !            60: @title Using GNU CC
        !            61: @end ifclear
        !            62: @sp 2
        !            63: @center Richard M. Stallman
        !            64: @sp 3
        !            65: @center last updated 15 February 1992
        !            66: @sp 1
        !            67: @center for version 2.0
        !            68: @center (preliminary draft, which will change)
        !            69: @page
        !            70: @vskip 0pt plus 1filll
        !            71: Copyright @copyright{} 1988, 1989, 1992 Free Software Foundation, Inc.
        !            72: 
        !            73: Permission is granted to make and distribute verbatim copies of
        !            74: this manual provided the copyright notice and this permission notice
        !            75: are preserved on all copies.
        !            76: 
        !            77: Permission is granted to copy and distribute modified versions of this
        !            78: manual under the conditions for verbatim copying, provided also that the
        !            79: section entitled ``GNU General Public License'' is included exactly as
        !            80: in the original, and provided that the entire resulting derived work is
        !            81: distributed under the terms of a permission notice identical to this one.
        !            82: 
        !            83: Permission is granted to copy and distribute translations of this manual
        !            84: into another language, under the above conditions for modified versions,
        !            85: except that the section entitled ``GNU General Public License'' and
        !            86: this permission notice may be included in translations approved by the
        !            87: Free Software Foundation instead of in the original English.
        !            88: @end titlepage
        !            89: @page
        !            90: 
        !            91: @ifinfo
        !            92: 
        !            93: @node Top, Copying,, (DIR)
        !            94: @ichapter Introduction
        !            95: @cindex introduction
        !            96: 
        !            97: @ifset INTERNALS
        !            98: This manual documents how to run, install and port the GNU C compiler, as
        !            99: well as its new features and incompatibilities, and how to report bugs.
        !           100: It corresponds to GNU CC version 2.0.
        !           101: @end ifset
        !           102: 
        !           103: @ifclear INTERNALS
        !           104: This manual documents how to run and install the GNU C compiler, as
        !           105: well as its new features and incompatibilities, and how to report bugs.
        !           106: It corresponds to GNU CC version 2.0.
        !           107: @end ifclear
        !           108: 
        !           109: @end ifinfo
        !           110: @ifset INTERNALS
        !           111: @menu
        !           112: * Copying::         GNU General Public License says
        !           113:                      how you can copy and share GNU CC.
        !           114: * Contributors::    People who have contributed to GNU CC.
        !           115: * Boycott::        Protect your freedom---fight ``look and feel''.
        !           116: * Invoking GCC::      Command options supported by @samp{gcc}.
        !           117: * Installation::    How to configure, compile and install GNU CC.
        !           118: * Trouble::         If you have trouble installing GNU CC.
        !           119: * Service::         How to find suppliers of support for GNU CC.
        !           120: * Incompatibilities:: Incompatibilities of GNU CC.
        !           121: * Extensions::      GNU extensions to the C language.
        !           122: * Bugs::            How to report bugs (if you want to get them fixed).
        !           123: * VMS::             Using GNU CC on VMS.
        !           124: * Portability::     Goals of GNU CC's portability features.
        !           125: * Interface::       Function-call interface of GNU CC output.
        !           126: * Passes::          Order of passes, what they do, and what each file is for.
        !           127: * RTL::             The intermediate representation that most passes work on.
        !           128: * Machine Desc::    How to write machine description instruction patterns.
        !           129: * Machine Macros::  How to write the machine description C macros.
        !           130: * Config::          Writing the @file{xm-@var{machine}.h} file.
        !           131: * Index::          Index of concepts and symbol names.
        !           132: @end menu
        !           133: @end ifset
        !           134: @ifclear INTERNALS
        !           135: @menu
        !           136: * Copying::         GNU General Public License says
        !           137:                      how you can copy and share GNU CC.
        !           138: * Contributors::    People who have contributed to GNU CC.
        !           139: * Boycott::        Protect your freedom---fight ``look and feel''.
        !           140: * Invoking GCC::      Command options supported by @samp{gcc}.
        !           141: * Installation::    How to configure, compile and install GNU CC.
        !           142: * Trouble::         If you have trouble installing GNU CC.
        !           143: * Service::         How to find suppliers of support for GNU CC.
        !           144: * Incompatibilities:: Incompatibilities of GNU CC.
        !           145: * Extensions::      GNU extensions to the C language.
        !           146: * Bugs::            How to report bugs (if you want to get them fixed).
        !           147: * VMS::             Using GNU CC on VMS.
        !           148: * Index::          Index of concepts and symbol names.
        !           149: @end menu
        !           150: @end ifclear
        !           151: 
        !           152: @node Copying, Contributors, Top, Top
        !           153: @unnumbered GNU GENERAL PUBLIC LICENSE
        !           154: @center Version 2, June 1991
        !           155: 
        !           156: @display
        !           157: Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
        !           158: 675 Mass Ave, Cambridge, MA 02139, USA
        !           159: 
        !           160: Everyone is permitted to copy and distribute verbatim copies
        !           161: of this license document, but changing it is not allowed.
        !           162: @end display
        !           163: 
        !           164: @unnumberedsec Preamble
        !           165: 
        !           166:   The licenses for most software are designed to take away your
        !           167: freedom to share and change it.  By contrast, the GNU General Public
        !           168: License is intended to guarantee your freedom to share and change free
        !           169: software---to make sure the software is free for all its users.  This
        !           170: General Public License applies to most of the Free Software
        !           171: Foundation's software and to any other program whose authors commit to
        !           172: using it.  (Some other Free Software Foundation software is covered by
        !           173: the GNU Library General Public License instead.)  You can apply it to
        !           174: your programs, too.
        !           175: 
        !           176:   When we speak of free software, we are referring to freedom, not
        !           177: price.  Our General Public Licenses are designed to make sure that you
        !           178: have the freedom to distribute copies of free software (and charge for
        !           179: this service if you wish), that you receive source code or can get it
        !           180: if you want it, that you can change the software or use pieces of it
        !           181: in new free programs; and that you know you can do these things.
        !           182: 
        !           183:   To protect your rights, we need to make restrictions that forbid
        !           184: anyone to deny you these rights or to ask you to surrender the rights.
        !           185: These restrictions translate to certain responsibilities for you if you
        !           186: distribute copies of the software, or if you modify it.
        !           187: 
        !           188:   For example, if you distribute copies of such a program, whether
        !           189: gratis or for a fee, you must give the recipients all the rights that
        !           190: you have.  You must make sure that they, too, receive or can get the
        !           191: source code.  And you must show them these terms so they know their
        !           192: rights.
        !           193: 
        !           194:   We protect your rights with two steps: (1) copyright the software, and
        !           195: (2) offer you this license which gives you legal permission to copy,
        !           196: distribute and/or modify the software.
        !           197: 
        !           198:   Also, for each author's protection and ours, we want to make certain
        !           199: that everyone understands that there is no warranty for this free
        !           200: software.  If the software is modified by someone else and passed on, we
        !           201: want its recipients to know that what they have is not the original, so
        !           202: that any problems introduced by others will not reflect on the original
        !           203: authors' reputations.
        !           204: 
        !           205:   Finally, any free program is threatened constantly by software
        !           206: patents.  We wish to avoid the danger that redistributors of a free
        !           207: program will individually obtain patent licenses, in effect making the
        !           208: program proprietary.  To prevent this, we have made it clear that any
        !           209: patent must be licensed for everyone's free use or not licensed at all.
        !           210: 
        !           211:   The precise terms and conditions for copying, distribution and
        !           212: modification follow.
        !           213: 
        !           214: @iftex
        !           215: @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
        !           216: @end iftex
        !           217: @ifinfo
        !           218: @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
        !           219: @end ifinfo
        !           220: 
        !           221: @enumerate
        !           222: @item
        !           223: This License applies to any program or other work which contains
        !           224: a notice placed by the copyright holder saying it may be distributed
        !           225: under the terms of this General Public License.  The ``Program'', below,
        !           226: refers to any such program or work, and a ``work based on the Program''
        !           227: means either the Program or any derivative work under copyright law:
        !           228: that is to say, a work containing the Program or a portion of it,
        !           229: either verbatim or with modifications and/or translated into another
        !           230: language.  (Hereinafter, translation is included without limitation in
        !           231: the term ``modification''.)  Each licensee is addressed as ``you''.
        !           232: 
        !           233: Activities other than copying, distribution and modification are not
        !           234: covered by this License; they are outside its scope.  The act of
        !           235: running the Program is not restricted, and the output from the Program
        !           236: is covered only if its contents constitute a work based on the
        !           237: Program (independent of having been made by running the Program).
        !           238: Whether that is true depends on what the Program does.
        !           239: 
        !           240: @item
        !           241: You may copy and distribute verbatim copies of the Program's
        !           242: source code as you receive it, in any medium, provided that you
        !           243: conspicuously and appropriately publish on each copy an appropriate
        !           244: copyright notice and disclaimer of warranty; keep intact all the
        !           245: notices that refer to this License and to the absence of any warranty;
        !           246: and give any other recipients of the Program a copy of this License
        !           247: along with the Program.
        !           248: 
        !           249: You may charge a fee for the physical act of transferring a copy, and
        !           250: you may at your option offer warranty protection in exchange for a fee.
        !           251: 
        !           252: @item
        !           253: You may modify your copy or copies of the Program or any portion
        !           254: of it, thus forming a work based on the Program, and copy and
        !           255: distribute such modifications or work under the terms of Section 1
        !           256: above, provided that you also meet all of these conditions:
        !           257: 
        !           258: @enumerate a
        !           259: @item
        !           260: You must cause the modified files to carry prominent notices
        !           261: stating that you changed the files and the date of any change.
        !           262: 
        !           263: @item
        !           264: You must cause any work that you distribute or publish, that in
        !           265: whole or in part contains or is derived from the Program or any
        !           266: part thereof, to be licensed as a whole at no charge to all third
        !           267: parties under the terms of this License.
        !           268: 
        !           269: @item
        !           270: If the modified program normally reads commands interactively
        !           271: when run, you must cause it, when started running for such
        !           272: interactive use in the most ordinary way, to print or display an
        !           273: announcement including an appropriate copyright notice and a
        !           274: notice that there is no warranty (or else, saying that you provide
        !           275: a warranty) and that users may redistribute the program under
        !           276: these conditions, and telling the user how to view a copy of this
        !           277: License.  (Exception: if the Program itself is interactive but
        !           278: does not normally print such an announcement, your work based on
        !           279: the Program is not required to print an announcement.)
        !           280: @end enumerate
        !           281: 
        !           282: These requirements apply to the modified work as a whole.  If
        !           283: identifiable sections of that work are not derived from the Program,
        !           284: and can be reasonably considered independent and separate works in
        !           285: themselves, then this License, and its terms, do not apply to those
        !           286: sections when you distribute them as separate works.  But when you
        !           287: distribute the same sections as part of a whole which is a work based
        !           288: on the Program, the distribution of the whole must be on the terms of
        !           289: this License, whose permissions for other licensees extend to the
        !           290: entire whole, and thus to each and every part regardless of who wrote it.
        !           291: 
        !           292: Thus, it is not the intent of this section to claim rights or contest
        !           293: your rights to work written entirely by you; rather, the intent is to
        !           294: exercise the right to control the distribution of derivative or
        !           295: collective works based on the Program.
        !           296: 
        !           297: In addition, mere aggregation of another work not based on the Program
        !           298: with the Program (or with a work based on the Program) on a volume of
        !           299: a storage or distribution medium does not bring the other work under
        !           300: the scope of this License.
        !           301: 
        !           302: @item
        !           303: You may copy and distribute the Program (or a work based on it,
        !           304: under Section 2) in object code or executable form under the terms of
        !           305: Sections 1 and 2 above provided that you also do one of the following:
        !           306: 
        !           307: @enumerate a
        !           308: @item
        !           309: Accompany it with the complete corresponding machine-readable
        !           310: source code, which must be distributed under the terms of Sections
        !           311: 1 and 2 above on a medium customarily used for software interchange; or,
        !           312: 
        !           313: @item
        !           314: Accompany it with a written offer, valid for at least three
        !           315: years, to give any third party, for a charge no more than your
        !           316: cost of physically performing source distribution, a complete
        !           317: machine-readable copy of the corresponding source code, to be
        !           318: distributed under the terms of Sections 1 and 2 above on a medium
        !           319: customarily used for software interchange; or,
        !           320: 
        !           321: @item
        !           322: Accompany it with the information you received as to the offer
        !           323: to distribute corresponding source code.  (This alternative is
        !           324: allowed only for noncommercial distribution and only if you
        !           325: received the program in object code or executable form with such
        !           326: an offer, in accord with Subsection b above.)
        !           327: @end enumerate
        !           328: 
        !           329: The source code for a work means the preferred form of the work for
        !           330: making modifications to it.  For an executable work, complete source
        !           331: code means all the source code for all modules it contains, plus any
        !           332: associated interface definition files, plus the scripts used to
        !           333: control compilation and installation of the executable.  However, as a
        !           334: special exception, the source code distributed need not include
        !           335: anything that is normally distributed (in either source or binary
        !           336: form) with the major components (compiler, kernel, and so on) of the
        !           337: operating system on which the executable runs, unless that component
        !           338: itself accompanies the executable.
        !           339: 
        !           340: If distribution of executable or object code is made by offering
        !           341: access to copy from a designated place, then offering equivalent
        !           342: access to copy the source code from the same place counts as
        !           343: distribution of the source code, even though third parties are not
        !           344: compelled to copy the source along with the object code.
        !           345: 
        !           346: @item
        !           347: You may not copy, modify, sublicense, or distribute the Program
        !           348: except as expressly provided under this License.  Any attempt
        !           349: otherwise to copy, modify, sublicense or distribute the Program is
        !           350: void, and will automatically terminate your rights under this License.
        !           351: However, parties who have received copies, or rights, from you under
        !           352: this License will not have their licenses terminated so long as such
        !           353: parties remain in full compliance.
        !           354: 
        !           355: @item
        !           356: You are not required to accept this License, since you have not
        !           357: signed it.  However, nothing else grants you permission to modify or
        !           358: distribute the Program or its derivative works.  These actions are
        !           359: prohibited by law if you do not accept this License.  Therefore, by
        !           360: modifying or distributing the Program (or any work based on the
        !           361: Program), you indicate your acceptance of this License to do so, and
        !           362: all its terms and conditions for copying, distributing or modifying
        !           363: the Program or works based on it.
        !           364: 
        !           365: @item
        !           366: Each time you redistribute the Program (or any work based on the
        !           367: Program), the recipient automatically receives a license from the
        !           368: original licensor to copy, distribute or modify the Program subject to
        !           369: these terms and conditions.  You may not impose any further
        !           370: restrictions on the recipients' exercise of the rights granted herein.
        !           371: You are not responsible for enforcing compliance by third parties to
        !           372: this License.
        !           373: 
        !           374: @item
        !           375: If, as a consequence of a court judgment or allegation of patent
        !           376: infringement or for any other reason (not limited to patent issues),
        !           377: conditions are imposed on you (whether by court order, agreement or
        !           378: otherwise) that contradict the conditions of this License, they do not
        !           379: excuse you from the conditions of this License.  If you cannot
        !           380: distribute so as to satisfy simultaneously your obligations under this
        !           381: License and any other pertinent obligations, then as a consequence you
        !           382: may not distribute the Program at all.  For example, if a patent
        !           383: license would not permit royalty-free redistribution of the Program by
        !           384: all those who receive copies directly or indirectly through you, then
        !           385: the only way you could satisfy both it and this License would be to
        !           386: refrain entirely from distribution of the Program.
        !           387: 
        !           388: If any portion of this section is held invalid or unenforceable under
        !           389: any particular circumstance, the balance of the section is intended to
        !           390: apply and the section as a whole is intended to apply in other
        !           391: circumstances.
        !           392: 
        !           393: It is not the purpose of this section to induce you to infringe any
        !           394: patents or other property right claims or to contest validity of any
        !           395: such claims; this section has the sole purpose of protecting the
        !           396: integrity of the free software distribution system, which is
        !           397: implemented by public license practices.  Many people have made
        !           398: generous contributions to the wide range of software distributed
        !           399: through that system in reliance on consistent application of that
        !           400: system; it is up to the author/donor to decide if he or she is willing
        !           401: to distribute software through any other system and a licensee cannot
        !           402: impose that choice.
        !           403: 
        !           404: This section is intended to make thoroughly clear what is believed to
        !           405: be a consequence of the rest of this License.
        !           406: 
        !           407: @item
        !           408: If the distribution and/or use of the Program is restricted in
        !           409: certain countries either by patents or by copyrighted interfaces, the
        !           410: original copyright holder who places the Program under this License
        !           411: may add an explicit geographical distribution limitation excluding
        !           412: those countries, so that distribution is permitted only in or among
        !           413: countries not thus excluded.  In such case, this License incorporates
        !           414: the limitation as if written in the body of this License.
        !           415: 
        !           416: @item
        !           417: The Free Software Foundation may publish revised and/or new versions
        !           418: of the General Public License from time to time.  Such new versions will
        !           419: be similar in spirit to the present version, but may differ in detail to
        !           420: address new problems or concerns.
        !           421: 
        !           422: Each version is given a distinguishing version number.  If the Program
        !           423: specifies a version number of this License which applies to it and ``any
        !           424: later version'', you have the option of following the terms and conditions
        !           425: either of that version or of any later version published by the Free
        !           426: Software Foundation.  If the Program does not specify a version number of
        !           427: this License, you may choose any version ever published by the Free Software
        !           428: Foundation.
        !           429: 
        !           430: @item
        !           431: If you wish to incorporate parts of the Program into other free
        !           432: programs whose distribution conditions are different, write to the author
        !           433: to ask for permission.  For software which is copyrighted by the Free
        !           434: Software Foundation, write to the Free Software Foundation; we sometimes
        !           435: make exceptions for this.  Our decision will be guided by the two goals
        !           436: of preserving the free status of all derivatives of our free software and
        !           437: of promoting the sharing and reuse of software generally.
        !           438: 
        !           439: @iftex
        !           440: @heading NO WARRANTY
        !           441: @end iftex
        !           442: @ifinfo
        !           443: @center NO WARRANTY
        !           444: @end ifinfo
        !           445: 
        !           446: @item
        !           447: BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
        !           448: FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
        !           449: OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
        !           450: PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
        !           451: OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
        !           452: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
        !           453: TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
        !           454: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
        !           455: REPAIR OR CORRECTION.
        !           456: 
        !           457: @item
        !           458: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
        !           459: WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
        !           460: REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
        !           461: INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
        !           462: OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
        !           463: TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
        !           464: YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
        !           465: PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
        !           466: POSSIBILITY OF SUCH DAMAGES.
        !           467: @end enumerate
        !           468: 
        !           469: @iftex
        !           470: @heading END OF TERMS AND CONDITIONS
        !           471: @end iftex
        !           472: @ifinfo
        !           473: @center END OF TERMS AND CONDITIONS
        !           474: @end ifinfo
        !           475: 
        !           476: @page
        !           477: @unnumberedsec Appendix: How to Apply These Terms to Your New Programs
        !           478: 
        !           479:   If you develop a new program, and you want it to be of the greatest
        !           480: possible use to the public, the best way to achieve this is to make it
        !           481: free software which everyone can redistribute and change under these terms.
        !           482: 
        !           483:   To do so, attach the following notices to the program.  It is safest
        !           484: to attach them to the start of each source file to most effectively
        !           485: convey the exclusion of warranty; and each file should have at least
        !           486: the ``copyright'' line and a pointer to where the full notice is found.
        !           487: 
        !           488: @smallexample
        !           489: @var{one line to give the program's name and a brief idea of what it does.}
        !           490: Copyright (C) 19@var{yy}  @var{name of author}
        !           491: 
        !           492: This program is free software; you can redistribute it and/or modify
        !           493: it under the terms of the GNU General Public License as published by
        !           494: the Free Software Foundation; either version 2 of the License, or
        !           495: (at your option) any later version.
        !           496: 
        !           497: This program is distributed in the hope that it will be useful,
        !           498: but WITHOUT ANY WARRANTY; without even the implied warranty of
        !           499: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        !           500: GNU General Public License for more details.
        !           501: 
        !           502: You should have received a copy of the GNU General Public License
        !           503: along with this program; if not, write to the Free Software
        !           504: Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
        !           505: @end smallexample
        !           506: 
        !           507: Also add information on how to contact you by electronic and paper mail.
        !           508: 
        !           509: If the program is interactive, make it output a short notice like this
        !           510: when it starts in an interactive mode:
        !           511: 
        !           512: @smallexample
        !           513: Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
        !           514: Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
        !           515: This is free software, and you are welcome to redistribute it
        !           516: under certain conditions; type `show c' for details.
        !           517: @end smallexample
        !           518: 
        !           519: The hypothetical commands @samp{show w} and @samp{show c} should show
        !           520: the appropriate parts of the General Public License.  Of course, the
        !           521: commands you use may be called something other than @samp{show w} and
        !           522: @samp{show c}; they could even be mouse-clicks or menu items---whatever
        !           523: suits your program.
        !           524: 
        !           525: You should also get your employer (if you work as a programmer) or your
        !           526: school, if any, to sign a ``copyright disclaimer'' for the program, if
        !           527: necessary.  Here is a sample; alter the names:
        !           528: 
        !           529: @example
        !           530: Yoyodyne, Inc., hereby disclaims all copyright interest in the program
        !           531: `Gnomovision' (which makes passes at compilers) written by James Hacker.
        !           532: 
        !           533: @var{signature of Ty Coon}, 1 April 1989
        !           534: Ty Coon, President of Vice
        !           535: @end example
        !           536: 
        !           537: This General Public License does not permit incorporating your program into
        !           538: proprietary programs.  If your program is a subroutine library, you may
        !           539: consider it more useful to permit linking proprietary applications with the
        !           540: library.  If this is what you want to do, use the GNU Library General
        !           541: Public License instead of this License.
        !           542: 
        !           543: @node Contributors, Boycott, Copying, Top
        !           544: @unnumbered Contributors to GNU CC
        !           545: @cindex contributors
        !           546: 
        !           547: In addition to Richard Stallman, several people have written parts
        !           548: of GNU CC.
        !           549: 
        !           550: @itemize @bullet
        !           551: @item
        !           552: The idea of using RTL and some of the optimization ideas came from the
        !           553: U. of Arizona Portable Optimizer, written by Jack Davidson and
        !           554: Christopher Fraser.  See ``Register Allocation and Exhaustive Peephole
        !           555: Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
        !           556: 857-866.
        !           557: 
        !           558: @item
        !           559: Paul Rubin wrote most of the preprocessor.
        !           560: 
        !           561: @item
        !           562: Leonard Tower wrote parts of the parser, RTL generator, and RTL
        !           563: definitions, and of the Vax machine description.
        !           564: 
        !           565: @item
        !           566: Ted Lemon wrote parts of the RTL reader and printer.
        !           567: 
        !           568: @item
        !           569: Jim Wilson implemented loop strength reduction and some other
        !           570: loop optimizations.
        !           571: 
        !           572: @item
        !           573: Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
        !           574: the support for the Sony NEWS machine.
        !           575: 
        !           576: @item
        !           577: Charles LaBrec contributed the support for the Integrated Solutions
        !           578: 68020 system.
        !           579: 
        !           580: @item
        !           581: Michael Tiemann of Cygnus Support wrote the front end for C++, as well
        !           582: as the support for inline functions and instruction scheduling.  Also
        !           583: the descriptions of the National Semiconductor 32000 series cpu, the
        !           584: SPARC cpu and part of the Motorola 88000 cpu.
        !           585: 
        !           586: @item
        !           587: Jan Stein of the Chalmers Computer Society provided support for
        !           588: Genix, as well as part of the 32000 machine description.
        !           589: 
        !           590: @item
        !           591: Randy Smith finished the Sun FPA support.
        !           592: 
        !           593: @item
        !           594: Robert Brown implemented the support for Encore 32000 systems.
        !           595: 
        !           596: @item
        !           597: David Kashtan of SRI adapted GNU CC to the Vomit-Making System (VMS).
        !           598: 
        !           599: @item
        !           600: Alex Crain provided changes for the 3b1.
        !           601: 
        !           602: @item
        !           603: Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
        !           604: the 9000 series 300.
        !           605: 
        !           606: @item
        !           607: William Schelter did most of the work on the Intel 80386 support.
        !           608: 
        !           609: @item
        !           610: Christopher Smith did the port for Convex machines.
        !           611: 
        !           612: @item
        !           613: Paul Petersen wrote the machine description for the Alliant FX/8.
        !           614: 
        !           615: @item
        !           616: Alain Lichnewsky ported GNU CC to the Mips cpu.
        !           617: 
        !           618: @item
        !           619: Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the Tahoe.
        !           620: 
        !           621: @item
        !           622: Jonathan Stone wrote the machine description for the Pyramid computer.
        !           623: 
        !           624: @item
        !           625: Richard Kenner of New York University wrote the machine descriptions for
        !           626: the AMD 29000, the IBM RT PC, and the IBM RS/6000 as well as the support
        !           627: for instruction attributes.  He also made changes to better support RISC
        !           628: processors including changes to common subexpression elimination,
        !           629: strength reduction, function calling sequence handling, and condition
        !           630: code support, in addition to generalizing the code for frame pointer
        !           631: elimination.
        !           632: 
        !           633: @item
        !           634: Richard Kenner and Michael Tiemann jointly developed reorg.c, the delay
        !           635: slot scheduler.
        !           636: 
        !           637: @item
        !           638: Mike Meissner and Tom Wood of Data General finished the port to the
        !           639: Motorola 88000.
        !           640: 
        !           641: @item 
        !           642: Masanobu Yuhara of Fujitsu Laboratories implemented the machine
        !           643: description for the Tron architecture (specifically, the Gmicro).
        !           644: 
        !           645: @item
        !           646: NeXT, Inc.@: donated the front end that supports the Objective C
        !           647: language.
        !           648: @c We need to be careful to make it clear that "Objective C"
        !           649: @c is the name of a language, not that of a program or product.
        !           650: 
        !           651: @item
        !           652: James van Artsdalen wrote the code that makes efficient use of
        !           653: the Intel 80387 register stack.
        !           654: 
        !           655: @item
        !           656: Mike Meissner at the Open Software Foundation finished the port to the
        !           657: MIPS cpu, including adding ECOFF debug support.
        !           658: 
        !           659: @item
        !           660: Ron Guilmette implemented the protoize and unprotoize tools, the support
        !           661: for Dwarf symbolic debugging information, and much of the support for
        !           662: System V Release 4.  He has also worked heavily on the Intel 386 and 860
        !           663: support.
        !           664: @end itemize
        !           665: 
        !           666: @node Boycott, Invoking GCC, Contributors, Top
        !           667: @chapter Protect Your Freedom---Fight ``Look And Feel''
        !           668: 
        !           669: @quotation
        !           670: @i{This section is a political message from the League for Programming
        !           671: Freedom to the users of GNU CC.  It is included here as an expression
        !           672: of support for the League on the part of the Free Software Foundation.}
        !           673: @end quotation
        !           674: 
        !           675: Apple, Lotus and Xerox are trying to create a new form of
        !           676: legal monopoly: a copyright on a class of user interfaces.  These
        !           677: monopolies would cause serious problems for users and developers of
        !           678: computer software and systems.
        !           679: 
        !           680: Until a few years ago, the law seemed clear: no one could restrict
        !           681: others from using a user interface; programmers were free to implement
        !           682: any interface they chose.  Imitating interfaces, sometimes with changes,
        !           683: was standard practice in the computer field.  The interfaces we know
        !           684: evolved gradually in this way; for example, the Macintosh user interface
        !           685: drew ideas from the Xerox interface, which in turn drew on work done at
        !           686: Stanford and SRI.  1-2-3 imitated VisiCalc, and dBase imitated a
        !           687: database program from JPL.
        !           688: 
        !           689: Most computer companies, and nearly all computer users, were happy with
        !           690: this state of affairs.  The companies that are suing say it does not
        !           691: offer ``enough incentive'' to develop their products, but they must have
        !           692: considered it ``enough'' when they made their decision to do so.  It
        !           693: seems they are not satisfied with the opportunity to continue to compete
        !           694: in the marketplace---not even with a head start.
        !           695: 
        !           696: If Xerox, Lotus, and Apple are permitted to make law through
        !           697: the courts, the precedent will hobble the software industry:
        !           698: 
        !           699: @itemize @bullet
        !           700: @item
        !           701: Gratuitous incompatibilities will burden users.  Imagine if each
        !           702: car manufacturer had to arrange the pedals in a different order.
        !           703: 
        !           704: @item
        !           705: Software will become and remain more expensive.  Users will be
        !           706: ``locked in'' to proprietary interfaces, for which there is no real
        !           707: competition.
        !           708: 
        !           709: @item
        !           710: Large companies have an unfair advantage wherever lawsuits become
        !           711: commonplace.  Since they can easily afford to sue, they can intimidate
        !           712: small companies with threats even when they don't really have a case.
        !           713: 
        !           714: @item
        !           715: User interface improvements will come slower, since incremental
        !           716: evolution through creative imitation will no longer be permitted.
        !           717: 
        !           718: @item
        !           719: Even Apple, etc., will find it harder to make improvements if
        !           720: they can no longer adapt the good ideas that others introduce, for
        !           721: fear of weakening their own legal positions.  Some users suggest that
        !           722: this stagnation may already have started.
        !           723: 
        !           724: @item
        !           725: If you use GNU software, you might find it of some concern that user
        !           726: interface copyright will make it hard for the Free Software Foundation
        !           727: to develop programs compatible with the interfaces that you already
        !           728: know.
        !           729: @end itemize
        !           730: 
        !           731: To protect our freedom from lawsuits like these, a group of programmers
        !           732: and users have formed a new grass-roots political organization, the
        !           733: League for Programming Freedom.
        !           734: 
        !           735: The purpose of the League is to oppose new monopolistic practices such
        !           736: as user-interface copyright and software patents; it calls for a return
        !           737: to the legal policies of the recent past, in which these practices were
        !           738: not allowed.  The League is not concerned with free software as an
        !           739: issue, and not affiliated with the Free Software Foundation.
        !           740: 
        !           741: The League's membership rolls include John McCarthy, inventor of Lisp,
        !           742: Marvin Minsky, founder of the Artificial Intelligence lab, Guy L.
        !           743: Steele, Jr., author of well-known books on Lisp and C, as well as
        !           744: Richard Stallman, the developer of GNU CC.  Please join and add your
        !           745: name to the list.  Membership dues in the League are $42 per year for
        !           746: programmers, managers and professionals; $10.50 for students; $21 for
        !           747: others.
        !           748: 
        !           749: The League needs both activist members and members who only pay their
        !           750: dues.
        !           751: 
        !           752: To join, or for more information, phone (617) 492-0023 or write to:
        !           753: 
        !           754: @display
        !           755: League for Programming Freedom
        !           756: 1 Kendall Square #143
        !           757: P.O. Box 9171
        !           758: Cambridge, MA 02139
        !           759: @end display
        !           760: 
        !           761: You can also send electronic mail to @code{league@@prep.ai.mit.edu}.
        !           762: 
        !           763: Here are some suggestions from the League for things you can do to
        !           764: protect your freedom to write programs:
        !           765: 
        !           766: @itemize @bullet
        !           767: @item
        !           768: Don't buy from Xerox, Lotus or Apple.  Buy from their competitors or
        !           769: from the defendants they are suing.
        !           770: 
        !           771: @item
        !           772: Don't develop software to work with the systems made by these companies.
        !           773: 
        !           774: @item
        !           775: Port your existing software to competing systems, so that you encourage
        !           776: users to switch.
        !           777: 
        !           778: @item
        !           779: Write letters to company presidents to let them know their conduct
        !           780: is unacceptable.
        !           781: 
        !           782: @item
        !           783: Tell your friends and colleagues about this issue and how it threatens
        !           784: to ruin the computer industry.
        !           785: 
        !           786: @item
        !           787: Above all, don't work for the look-and-feel plaintiffs, and don't
        !           788: accept contracts from them.
        !           789: 
        !           790: @item
        !           791: Write to Congress to explain the importance of this issue.
        !           792: 
        !           793: @display
        !           794: House Subcommittee on Intellectual Property
        !           795: 2137 Rayburn Bldg
        !           796: Washington, DC 20515
        !           797: 
        !           798: Senate Subcommittee on Patents, Trademarks and Copyrights
        !           799: United States Senate
        !           800: Washington, DC 20510
        !           801: @end display
        !           802: 
        !           803: (These committees have received lots of mail already; let's give them
        !           804: even more.)
        !           805: @end itemize
        !           806: 
        !           807: Express your opinion!  You can make a difference.
        !           808: 
        !           809: @include invoke.texi
        !           810: 
        !           811: @node Installation, Trouble, Invoking GCC, Top
        !           812: @chapter Installing GNU CC
        !           813: @cindex installing GNU CC
        !           814: 
        !           815: Here is the procedure for installing GNU CC on a Unix system.
        !           816: 
        !           817: @menu
        !           818: * Other Dir::     Compiling in a separate directory (not where the source is).
        !           819: * Sun Install::   See below for installation on the Sun.
        !           820: * 3B1 Install::   See below for installation on the 3B1.
        !           821: * VMS Install::   See below for installation on VMS.
        !           822: * SCO Install::   See below for installation on SCO System V 3.2.
        !           823:                     (This may also be a start on solving 
        !           824:                      the problems of installation on Xenix.)
        !           825: * Unos Install::  See below for installation on Unos (from CRDS).
        !           826: @end menu
        !           827: @iftex
        !           828: See below for VMS systems, and modified procedures needed on other
        !           829: systems including Sun, 3B1, SCO Unix and Unos.  The following section
        !           830: says how to compile in a separate directory on Unix; here we assume you
        !           831: compile in the same directory that contains the source files.
        !           832: @end iftex
        !           833: 
        !           834: @enumerate
        !           835: @item
        !           836: If you have built GNU CC previously in the same directory for a
        !           837: different target machine, do @samp{make cleanconfig} to delete all files
        !           838: that might be invalid.
        !           839: 
        !           840: @item
        !           841: On a Sequent system, go to the Berkeley universe.
        !           842: 
        !           843: @item
        !           844: On a System V release 4 system, make sure @file{/usr/bin} precedes
        !           845: @file{/usr/ucb} in @code{PATH}.  The @code{cc} command in
        !           846: @file{/usr/ucb} uses libraries which have bugs.
        !           847: 
        !           848: @item
        !           849: Specify the host and target machine configurations.  You do this by
        !           850: running the file @file{configure} with appropriate arguments.
        !           851: 
        !           852: If you are building a compiler to produce code for the machine it runs
        !           853: on, specify just one machine type.  To build a cross-compiler, specify
        !           854: two configurations, one for the @dfn{host machine} (which the compiler
        !           855: runs on), and one for the @dfn{target machine} (which the compiler
        !           856: produces code for).  The command looks like this:
        !           857: 
        !           858: @example
        !           859: configure --host=sun3-sunos3 --target=sparc-sun-sunos4.1
        !           860: @end example
        !           861: 
        !           862: A configuration name may be canonical or it may be more or less
        !           863: abbreviated.
        !           864: 
        !           865: A canonical configuration name has three parts, separated by dashes.
        !           866: It looks like this: @samp{@var{cpu}-@var{company}-@var{system}}.
        !           867: (The three parts may themselves contain dashes; @file{configure}
        !           868: can figure out which dashes serve which purpose.)  For example,
        !           869: @samp{m68k-sun-sunos4.1} specifies a Sun 3.
        !           870: 
        !           871: You can also replace parts of the configuration by nicknames or aliases.
        !           872: For example, @samp{sun3} stands for @samp{m68k-sun}, so
        !           873: @samp{sun3-sunos4.1} is another way to specify a Sun 3.  You can also
        !           874: use simply @samp{sun3-sunos}, since the version of Sunos is assumed by
        !           875: default to be version 4.  @samp{sun3-bsd} also works, since
        !           876: @file{configure} knows that the only BSD variant on a Sun 3 is Sunos.
        !           877: 
        !           878: You can specify a version number after any of the system types, and some
        !           879: of the CPU types.  In most cases, the version is irrelevant, and will be
        !           880: ignored.  So you might as well specify the version if you know it.
        !           881: 
        !           882: Here are the possible CPU types:
        !           883: 
        !           884: @quotation
        !           885: @c gmicro, pyramid, alliant, spur and tahoe omitted since they don't work.
        !           886: a29k, arm, c@var{n}, hppa, i386,
        !           887: i860, m68000, m68k, m88k, mips,
        !           888: ns32k, romp, rs6000, sparc, vax.
        !           889: @end quotation
        !           890: 
        !           891: Note that the type hppa currently works only with Berkeley systems,
        !           892: not with HP/UX.
        !           893: 
        !           894: Here are the recognized company names.  As you can see, customary
        !           895: abbreviations are used rather than the longer official names.
        !           896: 
        !           897: @quotation
        !           898: alliant, altos, apollo, att,
        !           899: convergent, convex, crds, dec, dg,
        !           900: encore, harris, hp, ibm, mips,
        !           901: motorola, ncr, next, ns, omron,
        !           902: sequent, sgi, sony, sun, tti,
        !           903: unicom.
        !           904: @end quotation
        !           905: 
        !           906: The company name is meaningful only to disambiguate when the rest of
        !           907: the information supplied is insufficient.  You can omit it, writing
        !           908: just @samp{@var{cpu}-@var{system}}, if it is not needed.  For example,
        !           909: @samp{vax-ultrix4.2} is equivalent to @samp{vax-dec-ultrix4.2}.
        !           910: 
        !           911: Here is a list of system types:
        !           912: 
        !           913: @quotation
        !           914: bsd, sysv, mach, minix, genix,
        !           915: ultrix, vms, sco, esix, isc,
        !           916: aix, sunos, hpux, unos,
        !           917: luna, dgux, newsos, osfrose, osf,
        !           918: dynix, aos, ctix.
        !           919: @end quotation
        !           920: 
        !           921: @noindent
        !           922: You can omit the system type; then @file{configure} guesses the
        !           923: operating system from the CPU and company.
        !           924: 
        !           925: Often a particular model of machine has a name.  Many of these names are
        !           926: recognized as an alias for a CPU/company combination.  The alias
        !           927: @samp{sun3}, mentioned above, is an example of this: it stands for
        !           928: @samp{m68k-sun}.  Sometimes we accept a company name as a machine name,
        !           929: when the name is popularly used for a particular machine.  Here is a
        !           930: table of the known machine names:
        !           931: 
        !           932: @quotation
        !           933: 3300, 3b1, 7300, altos3068, altos,
        !           934: apollo68, att-7300, balance,
        !           935: convex-c@var{n}, crds, decstation-3100,
        !           936: decstation-dec, decstation, delta, encore,
        !           937: gmicro, hp7@var{nn}, hp8@var{nn},
        !           938: hp9k2@var{nn}, hp9k3@var{nn}, hp9k7@var{nn},
        !           939: hp9k8@var{nn}, iris4d, iris, isi68,
        !           940: m3230, magnum, merlin, miniframe,
        !           941: mmax, news-3600, news800, news, next,
        !           942: pbd, pc532, pmax, ps2, risc-news,
        !           943: rtpc, sun2, sun386i, sun386, sun3,
        !           944: sun4, symmetry, tower-32, tower.
        !           945: @end quotation 
        !           946: 
        !           947: If you specify an impossible combination such as @samp{i860-dg-vms},
        !           948: then you may get an error message from @file{configure}, or it may
        !           949: ignore part of the information and do the best it can with the rest.
        !           950: @file{configure} always prints the canonical name for the alternative
        !           951: that it used.
        !           952: 
        !           953: On certain systems, you must specify whether you want GNU CC to work with
        !           954: the usual compilation tools or with the GNU compilation tools (including
        !           955: GAS).  Use the @samp{--gas} argument when you run @file{configure}, if
        !           956: you want to use the GNU tools.  The systems were this makes a difference
        !           957: are @samp{i386-@var{anything}-sysv}, @samp{i860-@var{anything}-bsd},
        !           958: @samp{m68k-hp-hpux}, @samp{m68k-sony-bsd}, @samp{m68k-altos-sysv},
        !           959: @samp{m68000-hp-hpux}, and @samp{m68000-att-sysv}.  On any other
        !           960: system, @samp{--gas} has no effect.
        !           961: 
        !           962: On certain systems, you must specify whether the machine has a floating
        !           963: point unit.  These systems are @samp{m68k-sun-sunos@var{n}} and
        !           964: @samp{m68k-isi-bsd}.  On any other system, @samp{--nfp} currently has no
        !           965: effect, though perhaps there are other systems where it could usefully
        !           966: make a difference.
        !           967: 
        !           968: If you want to install your own homemade configuration files, you can
        !           969: use @samp{local} as the company name to access them.  If you use 
        !           970: configuration @samp{@var{cpu}-local}, the entire configuration name
        !           971: is used to form the configuration file names.
        !           972: 
        !           973: Thus, if you specify @samp{m68k-local}, then the files used are
        !           974: @file{m68k-local.md}, @file{m68k-local.h}, @file{m68k-local.c},
        !           975: @file{xm-m68k-local.h}, @file{t-m68k-local}, and @file{x-m68k-local}.
        !           976: 
        !           977: Here is a list of configurations that have special treatment:
        !           978: 
        !           979: @table @samp
        !           980: @ignore
        !           981: @item fx80
        !           982: Alliant FX/8 computer.  Note that the standard installed C compiler in
        !           983: Concentrix 5.0 has a bug which prevent it from compiling GNU CC
        !           984: correctly.  You can patch the compiler bug as follows:
        !           985: 
        !           986: @example
        !           987: cp /bin/pcc ./pcc
        !           988: adb -w ./pcc - << EOF
        !           989: 15f6?w 6610
        !           990: EOF
        !           991: @end example
        !           992: 
        !           993: Then you must use the @samp{-ip12} option when compiling GNU CC
        !           994: with the patched compiler, as shown here:
        !           995: 
        !           996: @example
        !           997: make CC="./pcc -ip12" CFLAGS=-w
        !           998: @end example
        !           999: 
        !          1000: Note also that Alliant's version of DBX does not manage to work with the
        !          1001: output from GNU CC.
        !          1002: @end ignore
        !          1003: 
        !          1004: @item m68000-att
        !          1005: AT&T 3b1, a.k.a. 7300 PC.  Special procedures are needed to compile GNU
        !          1006: CC with this machine's standard C compiler, due to bugs in that
        !          1007: compiler.  @xref{3b1 Install}.  You can bootstrap it more easily with
        !          1008: previous versions of GNU CC if you have them.
        !          1009: 
        !          1010: @item m68000-hp-bsd
        !          1011: HP 9000 series 200 running BSD.  Note that the C compiler that comes
        !          1012: with this system cannot compile GNU CC; contact @code{law@@super.org}
        !          1013: to get binaries of GNU CC for bootstrapping.
        !          1014: 
        !          1015: @item m68k-altos
        !          1016: Altos 3068.  You must use the GNU assembler, linker and debugger, with
        !          1017: COFF-encapsulation.  Also, you must fix a kernel bug.  Details in the
        !          1018: file @file{ALTOS-README}.
        !          1019: 
        !          1020: @item m68k-hp-hpux
        !          1021: HP 9000 series 200 or 300 running HPUX.  GNU CC does not support the
        !          1022: special symbol table used by HP's debugger, but you can debug programs
        !          1023: with GDB if you specify @samp{--gas} to use the GNU tools instead.  In
        !          1024: order to use the GNU tools, you must install a library conversion
        !          1025: program called @code{hpxt}.
        !          1026: 
        !          1027: @item m68k-sun
        !          1028: Sun 3.  We do not provide a configuration file to use the Sun FPA by
        !          1029: default, because programs that establish signal handlers for floating
        !          1030: point traps inherently cannot work with the FPA.
        !          1031: 
        !          1032: @item m88k-dgux
        !          1033: Motorola m88k running DG/UX.  To build native or cross compilers on
        !          1034: DG/UX, you must first change to the 88open BCS software development
        !          1035: environment.  This is done by issuing this command:
        !          1036: 
        !          1037: @example
        !          1038: eval `sde-target m88kbcs`
        !          1039: @end example
        !          1040: 
        !          1041: @item ns32k-encore
        !          1042: Encore ns32000 system.  Encore systems are supported only under BSD.
        !          1043: 
        !          1044: @item ns32k-*-genix
        !          1045: National Semiconductor ns32000 system.  Genix has bugs in @code{alloca}
        !          1046: and @code{malloc}; you must get the compiled versions of these from GNU
        !          1047: Emacs.
        !          1048: 
        !          1049: @item ns32k-utek
        !          1050: UTEK ns32000 system (``merlin'').  The C compiler that comes with this
        !          1051: system cannot compile GNU CC; contact @samp{tektronix!reed!mason} to get
        !          1052: binaries of GNU CC for bootstrapping.
        !          1053: 
        !          1054: @item rs6000-ibm
        !          1055: IBM PowerStation/6000 machines.  Due to the nonstandard debugging
        !          1056: information required for this machine, @samp{-g} is not available in
        !          1057: this configuration.
        !          1058: 
        !          1059: @item vax-dec-ultrix
        !          1060: Don't try compiling with Vax C (@code{vcc}).  It produces incorrect code
        !          1061: in some cases (for example, when @code{alloca} is used).
        !          1062: 
        !          1063: Meanwhile, compiling @file{cp-parse.c} with pcc does not work because of
        !          1064: an internal table size limitation in that compiler.  To avoid this
        !          1065: problem, compile just the GNU C compiler first, and use it to recompile 
        !          1066: building all the languages that you want to run.
        !          1067: @end table
        !          1068: 
        !          1069: Here we spell out what files will be set up by @code{configure}.  Normally
        !          1070: you need not be concerned with these files.
        !          1071: 
        !          1072: @itemize @bullet
        !          1073: @item
        !          1074: @ifset INTERNALS
        !          1075: A symbolic link named @file{config.h} is made to the top-level config
        !          1076: file for the machine you will run the compiler on (@pxref{Config}).
        !          1077: This file is responsible for defining information about the host
        !          1078: machine.  It includes @file{tm.h}.
        !          1079: @end ifset
        !          1080: @ifclear INTERNALS
        !          1081: A symbolic link named @file{config.h} is made to the top-level config
        !          1082: file for the machine you plan to run the compiler on (@pxref{Config,,The
        !          1083: Configuration File, gcc.info, Using and Porting GCC}).  This file is
        !          1084: responsible for defining information about the host machine.  It
        !          1085: includes @file{tm.h}.
        !          1086: @end ifclear
        !          1087: 
        !          1088: The top-level config file is located in the subdirectory @file{config}.
        !          1089: Its name is always @file{xm-@var{something}.h}; usually
        !          1090: @file{xm-@var{machine}.h}, but there are some exceptions.
        !          1091: 
        !          1092: If your system does not support symbolic links, you might want to
        !          1093: set up @file{config.h} to contain a @samp{#include} command which
        !          1094: refers to the appropriate file.
        !          1095: 
        !          1096: @item
        !          1097: A symbolic link named @file{tconfig.h} is made to the top-level config
        !          1098: file for your target machine.  This is used for compiling certain
        !          1099: programs to run on that machine.
        !          1100: 
        !          1101: @item
        !          1102: A symbolic link named @file{tm.h} is made to the machine-description
        !          1103: macro file for your target machine.  It should be in the subdirectory
        !          1104: @file{config} and its name is often @file{@var{machine}.h}.
        !          1105: 
        !          1106: @item
        !          1107: A symbolic link named @file{md} will be made to the machine description
        !          1108: pattern file.  It should be in the @file{config} subdirectory and its
        !          1109: name should be @file{@var{machine}.md}; but @var{machine} is often not
        !          1110: the same as the name used in the @file{tm.h} file because the
        !          1111: @file{md} files are more general.
        !          1112: 
        !          1113: @item
        !          1114: A symbolic link named @file{aux-output.c} will be made to the output
        !          1115: subroutine file for your machine.  It should be in the @file{config}
        !          1116: subdirectory and its name should be @file{@var{machine}.c}.
        !          1117: 
        !          1118: @item
        !          1119: The command file @file{configure} also constructs @file{Makefile} by
        !          1120: adding some text to the template file @file{Makefile.in}.  The
        !          1121: additional text comes from files in the @file{config} directory, named
        !          1122: @file{t-@var{target}} and @file{h-@var{host}}.  If these files do not
        !          1123: exist, it means nothing needs to be added for a given target or host.
        !          1124: @end itemize
        !          1125: 
        !          1126: @cindex Bison parser generator
        !          1127: @cindex parser generator, Bison
        !          1128: @item
        !          1129: Make sure the Bison parser generator is installed.  (This is
        !          1130: unnecessary if the Bison output files @file{c-parse.c} and
        !          1131: @file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y}
        !          1132: and you do not plan to change the @samp{.y} files.)
        !          1133: 
        !          1134: Bison versions older than Sept 8, 1988 will produce incorrect output
        !          1135: for @file{c-parse.c}.
        !          1136: 
        !          1137: @item
        !          1138: Build the compiler.  Just type @samp{make LANGUAGES=c} in the compiler
        !          1139: directory.
        !          1140: 
        !          1141: @samp{LANGUAGES=c} specifies that only the C compiler should be
        !          1142: compiled.  The makefile normally builds compilers for all the supported
        !          1143: languages; currently, C, C++ and Objective C.  However, C is the only
        !          1144: language that is sure to work when you build with other non-GNU C
        !          1145: compilers.  In addition, building anything but C at this stage is a
        !          1146: waste of time.
        !          1147: 
        !          1148: In general, you can specify the languages to build by typing the
        !          1149: argument @samp{LANGUAGES="@var{list}"}, where @var{list} is one or more
        !          1150: words from the list @samp{c}, @samp{c++}, and @samp{objective-c}.
        !          1151: 
        !          1152: Ignore any warnings you may see about ``statement not reached'' in
        !          1153: @file{insn-emit.c}; they are normal.  Any other compilation errors may
        !          1154: represent bugs in the port to your machine or operating system, and
        !          1155: should be investigated and reported (@pxref{Bugs}).
        !          1156: 
        !          1157: Some commercial compilers fail to compile GNU CC because they have bugs
        !          1158: or limitations.  For example, the Microsoft compiler is said to run out
        !          1159: of macro space.  Some Ultrix compilers run out of expression space; then
        !          1160: you need to break up the statement where the problem happens.
        !          1161: 
        !          1162: @item
        !          1163: If you are using COFF-encapsulation, you must convert @file{libgcc.a} to
        !          1164: a GNU-format library at this point.  See the file @file{README-ENCAP}
        !          1165: in the directory containing the GNU binary file utilities, for
        !          1166: directions.
        !          1167: 
        !          1168: @cindex stage1
        !          1169: @item
        !          1170: Move the first-stage object files and executables into a subdirectory
        !          1171: with this command:
        !          1172: 
        !          1173: @example
        !          1174: make stage1
        !          1175: @end example
        !          1176: 
        !          1177: The files are moved into a subdirectory named @file{stage1}.
        !          1178: Once installation is complete, you may wish to delete these files
        !          1179: with @code{rm -r stage1}.
        !          1180: 
        !          1181: @item
        !          1182: Recompile the compiler with itself, with this command:
        !          1183: 
        !          1184: @example
        !          1185: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/"
        !          1186: @end example
        !          1187: 
        !          1188: This is called making the stage 2 compiler.
        !          1189: 
        !          1190: The command shown above builds compilers for all the supported
        !          1191: languages.  If you don't want them all, you can specify the languages to
        !          1192: build by typing the argument @samp{LANGUAGES="@var{list}"}.  @var{list}
        !          1193: should contain one or more words from the list @samp{c}, @samp{c++}, and
        !          1194: @samp{objective-c}, separated by spaces.
        !          1195: 
        !          1196: On a 68000 or 68020 system lacking floating point hardware,
        !          1197: unless you have selected a @file{tm.h} file that expects by default
        !          1198: that there is no such hardware, do this instead:
        !          1199: 
        !          1200: @example
        !          1201: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -msoft-float"
        !          1202: @end example
        !          1203: 
        !          1204: @item
        !          1205: If you wish to test the compiler by compiling it with itself one more
        !          1206: time, do this:
        !          1207: 
        !          1208: @example
        !          1209: make stage2
        !          1210: make CC=stage2/gcc CFLAGS="-g -O -Bstage2/" 
        !          1211: @end example
        !          1212: 
        !          1213: @noindent
        !          1214: This is called making the stage 3 compiler.  Aside from the @samp{-B}
        !          1215: option, the options should be the same as when you made the stage 2
        !          1216: compiler.
        !          1217: 
        !          1218: Then compare the latest object files with the stage 2 object
        !          1219: files---they ought to be identical, unless they contain time stamps.  On
        !          1220: systems where object files do not contain time stamps, you can do this
        !          1221: (in Bourne shell):
        !          1222: 
        !          1223: @example
        !          1224: for file in *.o; do
        !          1225: cmp $file stage2/$file
        !          1226: done
        !          1227: @end example
        !          1228: 
        !          1229: This will mention any object files that differ between stage 2 and stage
        !          1230: 3.  Any difference, no matter how innocuous, indicates that the stage 2
        !          1231: compiler has compiled GNU CC incorrectly, and is therefore a potentially
        !          1232: serious bug which you should investigate and report (@pxref{Bugs}).
        !          1233: 
        !          1234: On systems that use COFF object files, bytes 5 to 8 will always be
        !          1235: different, since it is a timestamp.  On these systems, you can do the
        !          1236: comparison as follows (in Bourne shell):
        !          1237: 
        !          1238: @example
        !          1239: for file in *.o; do
        !          1240: tail +10c $file > foo1
        !          1241: tail +10c stage2/$file > foo2
        !          1242: cmp foo1 foo2 || echo $file
        !          1243: done
        !          1244: @end example
        !          1245: 
        !          1246: On MIPS machines, you need to use the shell script @file{ecoff-cmp}
        !          1247: to compare two object files if you have built the compiler with
        !          1248: the @samp{-mno-mips-tfile} option.  Thus, do this:
        !          1249: 
        !          1250: @example
        !          1251: for file in *.o; do
        !          1252: ecoff-cmp $file stage2/$file
        !          1253: done
        !          1254: @end example
        !          1255: 
        !          1256: @item
        !          1257: Install the compiler driver, the compiler's passes and run-time support.
        !          1258: You can use the following command:
        !          1259: 
        !          1260: @example
        !          1261: make CC=stage2/gcc install
        !          1262: @end example
        !          1263: 
        !          1264: @noindent
        !          1265: (Use the same value for @code{CC} that you used when compiling the files
        !          1266: that are being installed.)
        !          1267: 
        !          1268: This copies the files @file{cc1}, @file{cpp} and @file{libgcc.a} to files
        !          1269: @file{cc1}, @file{cpp} and @file{libgcc.a} in directory
        !          1270: @file{/usr/local/lib/gcc/@var{target}/@var{version}}, which is where the
        !          1271: compiler driver program looks for them.  Here @var{target} is the target
        !          1272: machine type specified when you ran @file{configure}, and @var{version}
        !          1273: is the version number of GNU CC.  This naming scheme permits various
        !          1274: versions and/or cross-compilers to coexist.
        !          1275: 
        !          1276: It also copies the driver program @file{gcc} into the directory
        !          1277: @file{/usr/local/bin}, so that it appears in typical execution search
        !          1278: paths.@refill
        !          1279: 
        !          1280: @cindex @code{alloca} and SunOs
        !          1281: @strong{Warning: there is a bug in @code{alloca} in the Sun library.
        !          1282: To avoid this bug, install the binaries of GNU CC that were compiled
        !          1283: by GNU CC.  They use @code{alloca} as a built-in function and never
        !          1284: the one in the library.}
        !          1285: 
        !          1286: @item
        !          1287: If you will be using C++ or Objective C, and your operating system does
        !          1288: not handle constructors, then you must build and install the program
        !          1289: @code{collect2}.  Do this with the following command:
        !          1290: 
        !          1291: @example
        !          1292: make CC="stage2/gcc -O" install-collect2
        !          1293: @end example
        !          1294: 
        !          1295: The systems that @strong{do} handle constructors on their own include
        !          1296: system V release 4, and system V release 3 on the Intel 386.
        !          1297: 
        !          1298: Berkeley systems that use the ``a.out'' object file format handle
        !          1299: constructors without @code{collect2} if you use the GNU linker.  But if
        !          1300: you don't use the GNU linker, then you need @code{collect2} on these
        !          1301: systems.
        !          1302: 
        !          1303: @item
        !          1304: Build and install @code{protoize} if you want it.  Type
        !          1305: 
        !          1306: @example
        !          1307: make CC="stage2/gcc -O" install-proto
        !          1308: @end example
        !          1309: 
        !          1310: There is as yet no documentation for @code{protoize}.  Sorry.
        !          1311: 
        !          1312: @item
        !          1313: Correct errors in the header files on your machine.
        !          1314: 
        !          1315: Various system header files often contain constructs which are
        !          1316: incompatible with ANSI C, and they will not work when you compile
        !          1317: programs with GNU CC.  This behavior consists of substituting for macro
        !          1318: argument names when they appear inside of character constants.  The most
        !          1319: common offender is @file{ioctl.h}.
        !          1320: 
        !          1321: You can overcome this problem when you compile by specifying the
        !          1322: @samp{-traditional} option.
        !          1323: 
        !          1324: Alternatively, on Sun systems and 4.3BSD at least, you can correct the
        !          1325: include files by running the shell script @file{fixincludes}.  This
        !          1326: installs modified, corrected copies of the files @file{ioctl.h},
        !          1327: @file{ttychars.h} and many others, in a special directory where only
        !          1328: GNU CC will normally look for them.  This script will work on various
        !          1329: systems because it chooses the files by searching all the system
        !          1330: headers for the problem cases that we know about.
        !          1331: 
        !          1332: Use the following command to do this:
        !          1333: 
        !          1334: @example
        !          1335: make install-fixincludes
        !          1336: @end example
        !          1337: 
        !          1338: @noindent
        !          1339: If you selected a different directory for GNU CC installation when you
        !          1340: installed it, by specifying the Make variable @code{prefix} or
        !          1341: @code{libdir}, specify it the same way in this command.
        !          1342: 
        !          1343: Note that some systems are starting to come with ANSI C system header
        !          1344: files.  On these systems, don't run @file{fixincludes}; it may not work,
        !          1345: and is certainly not necessary.
        !          1346: @end enumerate
        !          1347: 
        !          1348: If you cannot install the compiler's passes and run-time support in
        !          1349: @file{/usr/local/lib}, you can alternatively use the @samp{-B} option to
        !          1350: specify a prefix by which they may be found.  The compiler concatenates
        !          1351: the prefix with the names  @file{cpp}, @file{cc1} and @file{libgcc.a}.
        !          1352: Thus, you can put the files in a directory @file{/usr/foo/gcc} and
        !          1353: specify @samp{-B/usr/foo/gcc/} when you run GNU CC.
        !          1354: 
        !          1355: Also, you can specify an alternative default directory for these files
        !          1356: by setting the Make variable @code{libdir} when you make GNU CC.
        !          1357: 
        !          1358: @node Other Dir, Sun Install, Installation, Installation
        !          1359: @section Compilation in a Separate Directory
        !          1360: @cindex other directory, compilation in
        !          1361: @cindex compilation in a separate directory
        !          1362: @cindex separate directory, compilation in
        !          1363: 
        !          1364: If you wish to build the object files and executables in a directory
        !          1365: other than the one containing the source files, here is what you must
        !          1366: do differently:
        !          1367: 
        !          1368: @enumerate
        !          1369: @item
        !          1370: Make sure you have a version of Make that supports the @code{VPATH}
        !          1371: feature.  (GNU Make supports it, as do Make versions on most BSD
        !          1372: systems.)
        !          1373: 
        !          1374: @item
        !          1375: Go to that directory before running @file{configure}:
        !          1376: 
        !          1377: @example
        !          1378: mkdir gcc-sun3
        !          1379: cd gcc-sun3
        !          1380: @end example
        !          1381: 
        !          1382: On systems that do not support symbolic links, this directory must be
        !          1383: on the same file system as the source code directory.
        !          1384: 
        !          1385: @item
        !          1386: Specify where to find @file{configure} when you run it:
        !          1387: 
        !          1388: @example
        !          1389: ../gcc-2.00/configure @dots{}
        !          1390: @end example
        !          1391: 
        !          1392: This also tells @code{configure} where to find the compiler sources;
        !          1393: @code{configure} takes the directory from the file name that was used to
        !          1394: invoke it.  But if you want to be sure, you can specify the source
        !          1395: directory with the @samp{--srcdir} option, like this:
        !          1396: 
        !          1397: @example
        !          1398: ../gcc-2.00/configure --srcdir=../gcc-2.00 sun3
        !          1399: @end example
        !          1400: 
        !          1401: The directory you specify with @samp{--srcdir} need not be the same
        !          1402: as the one that @code{configure} is found in.
        !          1403: @end enumerate
        !          1404: 
        !          1405: Now, you can run @code{make} in that directory.  You need not repeat the
        !          1406: configuration steps shown above, when ordinary source files change.  You
        !          1407: must, however, run @code{configure} again when the configuration files
        !          1408: change, if your system does not support symbolic links.
        !          1409: 
        !          1410: @node Sun Install, 3b1 Install, Other Dir, Installation
        !          1411: @section Installing GNU CC on the Sun
        !          1412: @cindex Sun installation
        !          1413: @cindex installing GNU CC on the Sun
        !          1414: 
        !          1415: Make sure the environment variable @code{FLOAT_OPTION} is not set when
        !          1416: you compile @file{libgcc.a}.  If this option were set to @code{f68881}
        !          1417: when @file{libgcc.a} is compiled, the resulting code would demand to be
        !          1418: linked with a special startup file and would not link properly without
        !          1419: special pains.
        !          1420: 
        !          1421: @cindex @code{alloca}, for SunOs
        !          1422: There is a bug in @code{alloca} in certain versions of the Sun library.
        !          1423: To avoid this bug, install the binaries of GNU CC that were compiled by
        !          1424: GNU CC.  They use @code{alloca} as a built-in function and never the one
        !          1425: in the library.
        !          1426: 
        !          1427: Some versions of the Sun compiler crash when compiling GNU CC.  The
        !          1428: problem is a segmentation fault in cpp.  This problem seems to be due to
        !          1429: the bulk of data in the environment variables.  You may be able to avoid
        !          1430: it by using the following command to compile GNU CC with Sun CC:
        !          1431: 
        !          1432: @example
        !          1433: make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc"
        !          1434: @end example
        !          1435: 
        !          1436: @node 3b1 Install, SCO Install, Sun Install, Installation
        !          1437: @section Installing GNU CC on the 3b1
        !          1438: @cindex 3b1 installation
        !          1439: @cindex installing GNU CC on the 3b1
        !          1440: 
        !          1441: Installing GNU CC on the 3b1 is difficult if you do not already have
        !          1442: GNU CC running, due to bugs in the installed C compiler.  However,
        !          1443: the following procedure might work.  We are unable to test it.
        !          1444: 
        !          1445: @enumerate
        !          1446: @item
        !          1447: Comment out the @samp{#include "config.h"} line on line 37 of
        !          1448: @file{cccp.c} and do @samp{make cpp}.  This makes a preliminary version
        !          1449: of GNU cpp.
        !          1450: 
        !          1451: @item
        !          1452: Save the old @file{/lib/cpp} and copy the preliminary GNU cpp to that
        !          1453: file name.
        !          1454: 
        !          1455: @item
        !          1456: Undo your change in @file{cccp.c}, or reinstall the original version,
        !          1457: and do @samp{make cpp} again.
        !          1458: 
        !          1459: @item
        !          1460: Copy this final version of GNU cpp into @file{/lib/cpp}.
        !          1461: 
        !          1462: @findex obstack_free
        !          1463: @item
        !          1464: Replace every occurrence of @code{obstack_free} in the file
        !          1465: @file{tree.c} with @code{_obstack_free}.
        !          1466: 
        !          1467: @item
        !          1468: Run @code{make} to get the first-stage GNU CC.
        !          1469: 
        !          1470: @item
        !          1471: Reinstall the original version of @file{/lib/cpp}.
        !          1472: 
        !          1473: @item
        !          1474: Now you can compile GNU CC with itself and install it in the normal
        !          1475: fashion.
        !          1476: @end enumerate
        !          1477: 
        !          1478: @node SCO Install, Unos Install, 3B1 Install, Installation
        !          1479: @section Installing GNU CC on SCO System V 3.2
        !          1480: @cindex SCO installation
        !          1481: @cindex installation on SCO systems
        !          1482: 
        !          1483: The compiler that comes with this system does not work properly with
        !          1484: @samp{-O}.  Therefore, you should redefine the Make variable
        !          1485: @code{CCLIBFLAGS} not to use @samp{-O}.
        !          1486: 
        !          1487: In addition, the compiler produces incorrect output when compiling parts
        !          1488: of GNU CC; the resulting executable @file{cc1} does not work properly
        !          1489: when it is used with @samp{-O}.
        !          1490: 
        !          1491: Therefore, what you must do after building the first stage
        !          1492: is use GNU CC to compile itself without optimization.  Here is how:
        !          1493: 
        !          1494: @example
        !          1495: make -k cc1 CC="./gcc -B./"
        !          1496: @end example
        !          1497: 
        !          1498: You can think of this as ``stage 1.1'' of the installation process.
        !          1499: However, using this command has the effect of discarding the faulty
        !          1500: stage 1 executable for @file{cc1} and replacing it with stage 1.1.  You
        !          1501: can then proceed with @samp{make stage1} and the rest of installation.
        !          1502: 
        !          1503: On Xenix, the same thing is necessary; in addition, you may have to
        !          1504: remove @samp{-g} from the options used with @code{cc}, and you may have
        !          1505: to simplify complicated statements in the sources of GNU CC to get them
        !          1506: to compile.
        !          1507: 
        !          1508: @node Unos Install, VMS Install, SCO Install, Installation
        !          1509: @section Installing GNU CC on Unos
        !          1510: @cindex Unos installation
        !          1511: @cindex installing GNU CC on Unos
        !          1512: 
        !          1513: Use @samp{configure unos} for building on Unos.
        !          1514: 
        !          1515: The Unos assembler is named @code{casm} instead of @code{as}.  For some
        !          1516: strange reason linking @file{/bin/as} to @file{/bin/casm} changes the
        !          1517: behavior, and does not work.  So, when installing GNU CC, you should
        !          1518: install the following script as @file{as} in the subdirectory where
        !          1519: the passes of GCC are installed:
        !          1520: 
        !          1521: @example
        !          1522: #!/bin/sh
        !          1523: casm $*
        !          1524: @end example
        !          1525: 
        !          1526: The default Unos library is named @file{libunos.a} instead of
        !          1527: @file{libc.a}.  To allow GNU CC to function, either change all
        !          1528: references to @samp{-lc} in @file{gcc.c} to @samp{-lunos} or link
        !          1529: @file{/lib/libc.a} to @file{/lib/libunos.a}.
        !          1530: 
        !          1531: @cindex @code{alloca}, for Unos
        !          1532: When compiling GNU CC with the standard compiler, to overcome bugs in
        !          1533: the support of @code{alloca}, do not use @samp{-O} when making stage 2.
        !          1534: Then use the stage 2 compiler with @samp{-O} to make the stage 3
        !          1535: compiler.  This compiler will have the same characteristics as the usual
        !          1536: stage 2 compiler on other systems.  Use it to make a stage 4 compiler
        !          1537: and compare that with stage 3 to verify proper compilation.
        !          1538: 
        !          1539: Unos uses memory segmentation instead of demand paging, so you will need
        !          1540: a lot of memory.  5 Mb is barely enough if no other tasks are running.
        !          1541: If linking @file{cc1} fails, try putting the object files into a library
        !          1542: and linking from that library.
        !          1543: 
        !          1544: @node VMS Install,, Unos Install, Installation
        !          1545: @section Installing GNU CC on VMS
        !          1546: @cindex VMS installation
        !          1547: @cindex installing GNU CC on VMS
        !          1548: 
        !          1549: The VMS version of GNU CC is distributed in a backup saveset containing
        !          1550: both source code and precompiled binaries.
        !          1551: 
        !          1552: To install the @file{gcc} command so you can use the compiler easily, in
        !          1553: the same manner as you use the VMS C compiler, you must install the VMS CLD
        !          1554: file for GNU CC as follows:
        !          1555: 
        !          1556: @enumerate
        !          1557: @item
        !          1558: Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE}
        !          1559: to point to the directories where the GNU CC executables
        !          1560: (@file{gcc-cpp}, @file{gcc-cc1}, etc.) and the C include files are
        !          1561: kept.  This should be done with the commands:@refill
        !          1562: 
        !          1563: @smallexample
        !          1564: $ assign /super /system disk:[gcc.] gnu_cc
        !          1565: $ assign /super /system disk:[gcc.include.] gnu_cc_include
        !          1566: @end smallexample
        !          1567: 
        !          1568: @noindent
        !          1569: with the appropriate disk and directory names.  These commands can be
        !          1570: placed in your system startup file so they will be executed whenever
        !          1571: the machine is rebooted.  You may, if you choose, do this via the
        !          1572: @file{GCC_INSTALL.COM} script in the @file{[GCC]} directory.
        !          1573: 
        !          1574: @item
        !          1575: Install the @file{GCC} command with the command line:
        !          1576: 
        !          1577: @smallexample
        !          1578: $ set command /table=sys$library:dcltables gnu_cc:[000000]gcc
        !          1579: @end smallexample
        !          1580: 
        !          1581: @item
        !          1582: To install the help file, do the following:
        !          1583: 
        !          1584: @smallexample
        !          1585: $ lib/help sys$library:helplib.hlb gcc.hlp
        !          1586: @end smallexample
        !          1587: 
        !          1588: @noindent
        !          1589: Now you can invoke the compiler with a command like @samp{gcc /verbose
        !          1590: file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in
        !          1591: Unix.
        !          1592: @end enumerate
        !          1593: 
        !          1594: If you wish to use GNU C++ you must first install GNU CC, and then
        !          1595: perform the following steps:
        !          1596: 
        !          1597: @enumerate
        !          1598: @item
        !          1599: Define the VMS logical name @samp{GNU_GXX_INCLUDE} to point to the
        !          1600: directory where the preprocessor will search for the C++ header files.
        !          1601: This can be done with the command:@refill
        !          1602: 
        !          1603: @smallexample
        !          1604: $ assign /super /system disk:[gcc.gxx_include.] gnu_gxx_include
        !          1605: @end smallexample
        !          1606: 
        !          1607: @noindent
        !          1608: with the appropriate disk and directory name.  If you are going to be
        !          1609: using libg++, you should place the libg++ header files in the directory
        !          1610: that this logical name points to.
        !          1611: 
        !          1612: @item
        !          1613: Obtain the file @file{gcc-cc1plus.exe}, and place this in the same
        !          1614: directory that @file{gcc-cc1.exe} is kept.
        !          1615: 
        !          1616: @item 
        !          1617: You will need several library functions which are used to call the
        !          1618: constructors and destructors for global objects.  These functions are
        !          1619: part of the libg++ distribution, and you will automatically get them if
        !          1620: you install libg++.
        !          1621: 
        !          1622: If you are not planning to install libg++, you will need to obtain the
        !          1623: files @file{gxx-startup-1.mar} and @file{gstart.cc} from the libg++
        !          1624: distribution, compile them, and supply them to the linker whenever you
        !          1625: link a C++ program.
        !          1626: 
        !          1627: The GNU C++ compiler can be invoked with a command like @samp{gcc /plus
        !          1628: /verbose file.cc}, which is equivalent to the command @samp{g++ -v -c
        !          1629: file.cc} in Unix.
        !          1630: @end enumerate
        !          1631: 
        !          1632: We try to put corresponding binaries and sources on the VMS distribution
        !          1633: tape.  But sometimes the binaries will be from an older version that the
        !          1634: sources, because we don't always have time to update them.  (Use the
        !          1635: @samp{/version} option to determine the version number of the binaries and
        !          1636: compare it with the source file @file{version.c} to tell whether this is
        !          1637: so.)  In this case, you should use the binaries you get to recompile the
        !          1638: sources.  If you must recompile, here is how:
        !          1639: 
        !          1640: @enumerate
        !          1641: @item
        !          1642: Copy the file @file{vms.h} to @file{tm.h}, @file{xm-vms.h} to
        !          1643: @file{config.h}, @file{vax.md} to @file{md.} and @file{vax.c}
        !          1644: to @file{aux-output.c}.  The files to be copied are found in the
        !          1645: subdirectory named @file{config}; they should be copied to the
        !          1646: main directory of GNU CC.  If you wish, you may use the command file
        !          1647: @file{config-gcc.com} to perform these steps for you.@refill
        !          1648: 
        !          1649: @item
        !          1650: Setup the logical names and command tables as defined above.  In
        !          1651: addition, define the VMS logical name @samp{GNU_BISON} to point at the
        !          1652: to the directories where the Bison executable is kept.  This should be
        !          1653: done with the command:@refill
        !          1654: 
        !          1655: @smallexample
        !          1656: $ assign /super /system disk:[bison.] gnu_bison
        !          1657: @end smallexample
        !          1658: 
        !          1659: You may, if you choose, use the @file{INSTALL_BISON.COM} script in the
        !          1660: @file{[BISON]} directory.
        !          1661: 
        !          1662: @item
        !          1663: Install the @samp{BISON} command with the command line:@refill
        !          1664: 
        !          1665: @smallexample
        !          1666: $ set command /table=sys$library:dcltables gnu_bison:[000000]bison
        !          1667: @end smallexample
        !          1668: 
        !          1669: @item
        !          1670: Type @samp{@@make-gcc} to recompile everything (alternatively, you may
        !          1671: submit the file @file{make-gcc.com} to a batch queue).  If you wish to
        !          1672: build the GNU C++ compiler as well as the GNU CC compiler, you must
        !          1673: first edit @file{make-gcc.com} and follow the instructions that appear
        !          1674: in the comments.@refill
        !          1675: 
        !          1676: @strong{If you are building GNU CC with a previous version of GNU CC,
        !          1677: you also should check to see that you have the newest version of the
        !          1678: assembler}.  In particular, GNU CC version 2 treats global constant
        !          1679: variables slightly differently from GNU CC version 1, and GAS version
        !          1680: 1.38.1 does not have the patches required to work with GCC version 2.
        !          1681: If you use GAS 1.38.1, then @code{extern const} variables will not have
        !          1682: the read-only bit set, and the linker will generate warning messages
        !          1683: about mismatched psect attributes for these variables.  These warning
        !          1684: messages are merely a nuisance, and can safely be ignored.
        !          1685: 
        !          1686: If you are compiling with a version of GNU CC older than 1.33, specify
        !          1687: @samp{/DEFINE=("inline=")} as an option in all the compilations.  This
        !          1688: requires editing all the @code{gcc} commands in @file{make-cc1.com}.
        !          1689: (The older versions had problems supporting @code{inline}.)  Once you
        !          1690: have a working 1.33 or newer GNU CC, you can change this file back.
        !          1691: @end enumerate
        !          1692: 
        !          1693: Under previous versions of GNU CC, the generated code would occasionally
        !          1694: give strange results when linked to the sharable @file{VAXCRTL} library.
        !          1695: Now this should work.
        !          1696: 
        !          1697: Even with this version, however, GNU CC itself should not be linked to
        !          1698: the sharable @file{VAXCRTL}.  The @code{qsort} routine supplied with
        !          1699: @file{VAXCRTL} has a bug which can cause a compiler crash.
        !          1700: 
        !          1701: Similarly, the preprocessor should not be linked to the sharable
        !          1702: @file{VAXCRTL}.  The @code{strncat} routine supplied with @file{VAXCRTL}
        !          1703: has a bug which can cause the preprocessor to go into an infinite loop.
        !          1704: 
        !          1705: If you attempt to link to the sharable @file{VAXCRTL}, the VMS linker
        !          1706: will strongly resist any effort to force it to use the @code{qsort} and
        !          1707: @code{strncat} routines from @file{gcclib}.  Until the bugs in
        !          1708: @file{VAXCRTL} have been fixed, linking any of the compiler components
        !          1709: to the sharable VAXCRTL is not recommended.  (These routines can be
        !          1710: bypassed by placing duplicate copies of @code{qsort} and @code{strncat}
        !          1711: in @file{gcclib} under different names, and patching the compiler
        !          1712: sources to use these routines).  Both of the bugs in @file{VAXCRTL} are
        !          1713: still present in VMS version 5.4-1, which is the most recent version as
        !          1714: of this writing.
        !          1715: 
        !          1716: The executables that are generated by @file{make-cc1.com} and
        !          1717: @file{make-cccp.com} use the nonshared version of @file{VAXCRTL} (and
        !          1718: thus use the @code{qsort} and @code{strncat} routines from
        !          1719: @file{gcclib.olb}).
        !          1720: 
        !          1721: @node Trouble, Service, Installation, Top
        !          1722: @chapter Known Causes of Trouble with GNU CC
        !          1723: @cindex bugs, known
        !          1724: @cindex installation trouble
        !          1725: @cindex known causes of trouble
        !          1726: 
        !          1727: Here are some of the things that have caused trouble for people installing
        !          1728: or using GNU CC.
        !          1729: 
        !          1730: @itemize @bullet
        !          1731: @item
        !          1732: On certain systems, defining certain environment variables such as
        !          1733: @code{CC} can interfere with the functioning of @code{make}.
        !          1734: 
        !          1735: @item
        !          1736: Cross compilation can run into trouble for certain machines because
        !          1737: some target machines' assemblers require floating point numbers to be
        !          1738: written as @emph{integer} constants in certain contexts.
        !          1739: 
        !          1740: The compiler writes these integer constants by examining the floating
        !          1741: point value as an integer and printing that integer, because this is
        !          1742: simple to write and independent of the details of the floating point
        !          1743: representation.  But this does not work if the compiler is running on
        !          1744: a different machine with an incompatible floating point format, or
        !          1745: even a different byte-ordering.
        !          1746: 
        !          1747: In addition, correct constant folding of floating point values
        !          1748: requires representing them in the target machine's format.
        !          1749: (The C standard does not quite require this, but in practice
        !          1750: it is the only way to win.)
        !          1751: 
        !          1752: @ifset INTERNALS
        !          1753: It is now possible to overcome these problems by defining macros such
        !          1754: as @code{REAL_VALUE_TYPE}.  But doing so is a substantial amount of
        !          1755: work for each target machine.  @xref{Cross-compilation}.
        !          1756: @end ifset
        !          1757: @ifclear INTERNALS
        !          1758: It is now possible to overcome these problems by defining macros such
        !          1759: as @code{REAL_VALUE_TYPE}.  But doing so is a substantial amount of
        !          1760: work for each target machine.  @xref{Cross-compilation,,Cross
        !          1761: Compilation and Floating Point Format, gcc.info, Using and Porting GCC}.
        !          1762: @end ifclear
        !          1763: 
        !          1764: @cindex promotion of formal parameters
        !          1765: @item
        !          1766: Users often think it is a bug when GNU CC reports an error for code
        !          1767: like this:
        !          1768: 
        !          1769: @example
        !          1770: int foo (short);
        !          1771: 
        !          1772: int foo (x)
        !          1773:      short x;
        !          1774: @{@dots{}@}
        !          1775: @end example
        !          1776: 
        !          1777: The error message is correct: this code really is erroneous, because the
        !          1778: old-style non-prototype definition passes subword integers in their
        !          1779: promoted types.  In other words, the argument is really an @code{int},
        !          1780: not a @code{short}.  The correct prototype is this:
        !          1781: 
        !          1782: @example
        !          1783: int foo (int);
        !          1784: @end example
        !          1785: 
        !          1786: @cindex conflicting types
        !          1787: @cindex scope of declaration
        !          1788: @item
        !          1789: Users often think it is a bug when GNU CC reports an error for code
        !          1790: like this:
        !          1791: 
        !          1792: @example
        !          1793: int foo (struct mumble *);
        !          1794: 
        !          1795: struct mumble @{ @dots{} @};
        !          1796: 
        !          1797: int foo (struct mumble *x)
        !          1798: @{ @dots{} @}
        !          1799: @end example
        !          1800: 
        !          1801: This code really is erroneous, because the scope of @code{struct
        !          1802: mumble} the prototype is limited to the argument list containing it.
        !          1803: It does not refer to the @code{struct mumble} defined with file scope
        !          1804: immediately below---they are two unrelated types with similar names in
        !          1805: different scopes.
        !          1806: 
        !          1807: But in the definition of @code{foo}, the file-scope type is used
        !          1808: because that is available to be inherited.  Thus, the definition and
        !          1809: the prototype do not match, and you get an error.
        !          1810: 
        !          1811: This behavior may seem silly, but it's what the ANSI standard specifies.
        !          1812: It is easy enough for you to make your code work by moving the
        !          1813: definition of @code{struct mumble} above the prototype.  It's not worth
        !          1814: being incompatible with ANSI C just to avoid an error for the example
        !          1815: shown above.
        !          1816: 
        !          1817: @item
        !          1818: Certain local variables aren't recognized by debuggers when you compile
        !          1819: with optimization.
        !          1820: 
        !          1821: This occurs because sometimes GNU CC optimizes the variable out of
        !          1822: existence.  There is no way to tell the debugger how to compute the
        !          1823: value such a variable ``would have had'', and it is not clear that would
        !          1824: be desirable anyway.  So GNU CC simply does not mention the eliminated
        !          1825: variable when it writes debugging information.
        !          1826: 
        !          1827: You have to expect a certain amount of disagreement between the
        !          1828: executable and your source code, when you use optimization.
        !          1829: 
        !          1830: @ignore
        !          1831: @cindex @code{vfork}, for the Sun-4
        !          1832: @item
        !          1833: There is a bug in @code{vfork} on the Sun-4 which causes the registers
        !          1834: of the child process to clobber those of the parent.  Because of this,
        !          1835: programs that call @code{vfork} are likely to lose when compiled
        !          1836: optimized with GNU CC when the child code alters registers which contain
        !          1837: C variables in the parent.  This affects variables which are live in the
        !          1838: parent across the call to @code{vfork}.
        !          1839: 
        !          1840: If you encounter this, you can work around the problem by declaring
        !          1841: variables @code{volatile} in the function that calls @code{vfork}, until
        !          1842: the problem goes away, or by not declaring them @code{register} and not
        !          1843: using @samp{-O} for those source files.
        !          1844: @end ignore
        !          1845: 
        !          1846: @item
        !          1847: @code{-2147483648} is positive.
        !          1848: 
        !          1849: This is because 2147483648 cannot fit in the type @code{int}, so
        !          1850: (following the ANSI C rules) its data type is @code{unsigned long int}.
        !          1851: Negating this value yields 2147483648 again.
        !          1852: 
        !          1853: @cindex @code{genflags}, crash on Sun 4
        !          1854: @item
        !          1855: Sometimes on a Sun 4 you may observe a crash in the program
        !          1856: @code{genflags} while building GCC.  This is said to be due to a bug in
        !          1857: @code{sh}.  You can probably get around it by running @code{genflags}
        !          1858: manually and then retrying the @code{make}.
        !          1859: 
        !          1860: @item 
        !          1861: On some versions of Ultrix, the system supplied compiler cannot compile
        !          1862: @file{cp-parse.c} because it cannot handle so many cases in a @code{switch}
        !          1863: statement.  You can work around this problem by compiling with GNU CC.
        !          1864: 
        !          1865: @item
        !          1866: On some BSD systems including some versions of Ultrix, use of profiling
        !          1867: causes static variable destructors (currently used only in C++) not to
        !          1868: be run.
        !          1869: 
        !          1870: @item
        !          1871: On the IBM RS/6000, compiling code of the form
        !          1872: 
        !          1873: @example
        !          1874: extern int foo;
        !          1875: 
        !          1876: @dots{} foo @dots{}
        !          1877: 
        !          1878: static int foo;
        !          1879: @end example
        !          1880: 
        !          1881: @noindent
        !          1882: will cause the linker to report an undefined symbol @code{foo}.
        !          1883: Although this behavior differs from most other systems, it is not a
        !          1884: bug because redefining an @code{extern} variable as @code{static}
        !          1885: is undefined in ANSI C.
        !          1886: @end itemize
        !          1887: 
        !          1888: For additional common problems, see @ref{Incompatibilities}.
        !          1889: 
        !          1890: @node Service, Incompatibilities, Trouble, Top
        !          1891: @chapter How To Get Help with GNU CC
        !          1892: 
        !          1893: If you need help installing, using or changing GNU CC, there are two
        !          1894: ways to find it:
        !          1895: 
        !          1896: @itemize @bullet
        !          1897: @item
        !          1898: Send a message to a suitable network mailing list.  First try
        !          1899: @code{bug-gcc@@prep.ai.mit.edu}, and if that brings no response, try
        !          1900: @code{help-gcc@@prep.ai.mit.edu}.
        !          1901: 
        !          1902: @item
        !          1903: Look in the service directory for someone who might help you for a fee.
        !          1904: The service directory is found in the file named @file{SERVICE} in the
        !          1905: GNU CC distribution.
        !          1906: @end itemize
        !          1907: 
        !          1908: @node Incompatibilities, Extensions, Service, Top
        !          1909: @chapter Incompatibilities of GNU CC
        !          1910: @cindex incompatibilities of GNU CC
        !          1911: 
        !          1912: There are several noteworthy incompatibilities between GNU C and most
        !          1913: existing (non-ANSI) versions of C.  The @samp{-traditional} option
        !          1914: eliminates most of these incompatibilities, @emph{but not all}, by
        !          1915: telling GNU C to behave like the other C compilers.
        !          1916: 
        !          1917: @itemize @bullet
        !          1918: @cindex string constants
        !          1919: @cindex read-only strings
        !          1920: @cindex shared strings
        !          1921: @item
        !          1922: GNU CC normally makes string constants read-only.  If several
        !          1923: identical-looking string constants are used, GNU CC stores only one
        !          1924: copy of the string.
        !          1925: 
        !          1926: @cindex @code{mktemp}, and constant strings
        !          1927: One consequence is that you cannot call @code{mktemp} with a string
        !          1928: constant argument.  The function @code{mktemp} always alters the
        !          1929: string its argument points to.
        !          1930: 
        !          1931: @cindex @code{sscanf}, and constant strings
        !          1932: @cindex @code{fscanf}, and constant strings
        !          1933: @cindex @code{scanf}, and constant strings
        !          1934: Another consequence is that @code{sscanf} does not work on some systems
        !          1935: when passed a string constant as its format control string or input.
        !          1936: This is because @code{sscanf} incorrectly tries to write into the string
        !          1937: constant.  Likewise @code{fscanf} and @code{scanf}.
        !          1938: 
        !          1939: The best solution to these problems is to change the program to use
        !          1940: @code{char}-array variables with initialization strings for these
        !          1941: purposes instead of string constants.  But if this is not possible,
        !          1942: you can use the @samp{-fwritable-strings} flag, which directs GNU CC
        !          1943: to handle string constants the same way most C compilers do.
        !          1944: @samp{-traditional} also has this effect, among others.
        !          1945: 
        !          1946: @item
        !          1947: GNU CC does not substitute macro arguments when they appear inside of
        !          1948: string constants.  For example, the following macro in GNU CC
        !          1949: 
        !          1950: @example
        !          1951: #define foo(a) "a"
        !          1952: @end example
        !          1953: 
        !          1954: @noindent
        !          1955: will produce output @code{"a"} regardless of what the argument @var{a} is.
        !          1956: 
        !          1957: The @samp{-traditional} option directs GNU CC to handle such cases
        !          1958: (among others) in the old-fashioned (non-ANSI) fashion.
        !          1959: 
        !          1960: @cindex @code{setjmp} incompatibilities
        !          1961: @cindex @code{longjmp} incompatibilities
        !          1962: @item
        !          1963: When you use @code{setjmp} and @code{longjmp}, the only automatic
        !          1964: variables guaranteed to remain valid are those declared
        !          1965: @code{volatile}.  This is a consequence of automatic register
        !          1966: allocation.  Consider this function:
        !          1967: 
        !          1968: @example
        !          1969: jmp_buf j;
        !          1970: 
        !          1971: foo ()
        !          1972: @{
        !          1973:   int a, b;
        !          1974: 
        !          1975:   a = fun1 ();
        !          1976:   if (setjmp (j))
        !          1977:     return a;
        !          1978: 
        !          1979:   a = fun2 ();
        !          1980:   /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
        !          1981:   return a + fun3 ();
        !          1982: @}
        !          1983: @end example
        !          1984: 
        !          1985: Here @code{a} may or may not be restored to its first value when the
        !          1986: @code{longjmp} occurs.  If @code{a} is allocated in a register, then
        !          1987: its first value is restored; otherwise, it keeps the last value stored
        !          1988: in it.
        !          1989: 
        !          1990: If you use the @samp{-W} option with the @samp{-O} option, you will
        !          1991: get a warning when GNU CC thinks such a problem might be possible.
        !          1992: 
        !          1993: The @samp{-traditional} option directs GNU C to put variables in
        !          1994: the stack by default, rather than in registers, in functions that
        !          1995: call @code{setjmp}.  This results in the behavior found in
        !          1996: traditional C compilers.
        !          1997: 
        !          1998: @cindex external declaration scope
        !          1999: @cindex scope of external declarations
        !          2000: @cindex declaration scope
        !          2001: @item
        !          2002: Declarations of external variables and functions within a block apply
        !          2003: only to the block containing the declaration.  In other words, they
        !          2004: have the same scope as any other declaration in the same place.
        !          2005: 
        !          2006: In some other C compilers, a @code{extern} declaration affects all the
        !          2007: rest of the file even if it happens within a block.
        !          2008: 
        !          2009: The @samp{-traditional} option directs GNU C to treat all @code{extern}
        !          2010: declarations as global, like traditional compilers.
        !          2011: 
        !          2012: @item
        !          2013: In traditional C, you can combine @code{long}, etc., with a typedef name,
        !          2014: as shown here:
        !          2015: 
        !          2016: @example
        !          2017: typedef int foo;
        !          2018: typedef long foo bar;
        !          2019: @end example
        !          2020: 
        !          2021: In ANSI C, this is not allowed: @code{long} and other type modifiers
        !          2022: require an explicit @code{int}.  Because this criterion is expressed
        !          2023: by Bison grammar rules rather than C code, the @samp{-traditional}
        !          2024: flag cannot alter it.
        !          2025: 
        !          2026: @cindex typedef names as function parameters
        !          2027: @item
        !          2028: PCC allows typedef names to be used as function parameters.  The
        !          2029: difficulty described immediately above applies here too.
        !          2030: 
        !          2031: @cindex whitespace
        !          2032: @item
        !          2033: PCC allows whitespace in the middle of compound assignment operators
        !          2034: such as @samp{+=}.  GNU CC, following the ANSI standard, does not
        !          2035: allow this.  The difficulty described immediately above applies here
        !          2036: too.
        !          2037: 
        !          2038: @cindex apostrophes
        !          2039: @cindex '
        !          2040: @item
        !          2041: GNU CC will flag unterminated character constants inside of preprocessor
        !          2042: conditionals that fail.  Some programs have English comments enclosed in
        !          2043: conditionals that are guaranteed to fail; if these comments contain
        !          2044: apostrophes, GNU CC will probably report an error.  For example,
        !          2045: this code would produce an error:
        !          2046: 
        !          2047: @example
        !          2048: #if 0
        !          2049: You can't expect this to work.
        !          2050: #endif
        !          2051: @end example
        !          2052: 
        !          2053: The best solution to such a problem is to put the text into an actual
        !          2054: C comment delimited by @samp{/*@dots{}*/}.  However,
        !          2055: @samp{-traditional} suppresses these error messages.
        !          2056: 
        !          2057: @cindex @code{float} as function value type
        !          2058: @item
        !          2059: When compiling functions that return @code{float}, PCC converts it to
        !          2060: a double.  GNU CC actually returns a @code{float}.  If you are concerned
        !          2061: with PCC compatibility, you should declare your functions to return
        !          2062: @code{double}; you might as well say what you mean.
        !          2063: 
        !          2064: @cindex structures
        !          2065: @cindex unions
        !          2066: @item
        !          2067: When compiling functions that return structures or unions, GNU CC
        !          2068: output code normally uses a method different from that used on most
        !          2069: versions of Unix.  As a result, code compiled with GNU CC cannot call
        !          2070: a structure-returning function compiled with PCC, and vice versa.
        !          2071: 
        !          2072: The method used by GNU CC is as follows: a structure or union which is
        !          2073: 1, 2, 4 or 8 bytes long is returned like a scalar.  A structure or union
        !          2074: with any other size is stored into an address supplied by the caller
        !          2075: (usually in a special, fixed register, but on some machines it is passed
        !          2076: on the stack).  The machine-description macros @code{STRUCT_VALUE} and
        !          2077: @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address.
        !          2078: 
        !          2079: By contrast, PCC on most target machines returns structures and unions
        !          2080: of any size by copying the data into an area of static storage, and then
        !          2081: returning the address of that storage as if it were a pointer value.
        !          2082: The caller must copy the data from that memory area to the place where
        !          2083: the value is wanted.  GNU CC does not use this method because it is
        !          2084: slower and nonreentrant.
        !          2085: 
        !          2086: On some newer machines, PCC uses a reentrant convention for all
        !          2087: structure and union returning.  GNU CC on most of these machines uses a
        !          2088: compatible convention when returning structures and unions in memory,
        !          2089: but still returns small structures and unions in registers.
        !          2090: 
        !          2091: You can tell GNU CC to use a compatible convention for all structure and
        !          2092: union returning with the option @samp{-fpcc-struct-return}.
        !          2093: @end itemize
        !          2094: 
        !          2095: There are also system-specific incompatibilities.
        !          2096: 
        !          2097: @itemize @bullet
        !          2098: @ignore
        !          2099: @c wfs@@nicholas.ma.utexas.edu says that this problem is solved 
        !          2100: @c provided alloca always adds 0x60 extra bytes to form a new save area
        !          2101: @c and avoids overlapping the old one.  And it seems that GCC
        !          2102: @c already does this.  So he thinks this problem is gone.
        !          2103: 
        !          2104: @item 
        !          2105: @cindex Sparc
        !          2106: The Sparc version of @code{setjmp} interacts badly with unexpected stack
        !          2107: adjustments.  With rare exceptions, you cannot use @code{setjmp} in a
        !          2108: function which moves the stack pointer.
        !          2109: 
        !          2110: In the current version of GNU CC, there are two ways that the stack
        !          2111: pointer can change value: (1) calls to @code{alloca}, and (2) use of
        !          2112: variable-sized objects.  You should avoid both in functions that call
        !          2113: @code{setjmp}.
        !          2114: 
        !          2115: The cause of the problem is the way that Sun implemented register
        !          2116: windows.  The 96 bytes at addresses @code{%sp} through @code{%sp+95}
        !          2117: correspond to the register window save area.  When a register window
        !          2118: must be spilled, its stack pointer is located, and the registers are
        !          2119: dumped starting at that address.  Similarly, when a register window must
        !          2120: be restored, its stack pointer is located, and the registers are
        !          2121: restored from that address.
        !          2122: 
        !          2123: When @code{setjmp} is called, the current register window's registers
        !          2124: are saved into the register save area, and the address of this save area
        !          2125: is stored into the @code{jmp_buf}.  Other subsequent function calls
        !          2126: store newer values of the registers into the same save area; that is ok.
        !          2127: When @code{longjmp} is called, the registers are restored using that
        !          2128: address.  (Actually, @emph{all} register windows are restored from all
        !          2129: valid register windows at the time @code{longjmp} is called.)
        !          2130: 
        !          2131: This scheme assumes that the stack pointer does not change after the
        !          2132: call to @code{setjmp}.  If the pointer changes, @code{longjmp} will
        !          2133: restore using the old stack value, which may obtain garbage.
        !          2134: @end ignore
        !          2135: @cindex Alliant
        !          2136: @item
        !          2137: On the Alliant, the system's own convention for returning structures
        !          2138: and unions is unusual, and is not compatible with GNU CC no matter
        !          2139: what options are used.
        !          2140: 
        !          2141: @cindex RT PC
        !          2142: @cindex IBM RT PC
        !          2143: @item
        !          2144: On the IBM RT PC, the MetaWare HighC compiler (hc) uses yet another
        !          2145: convention for structure and union returning.  Use
        !          2146: @samp{-mhc-struct-return} to tell GNU CC to use a convention compatible
        !          2147: with it.
        !          2148: 
        !          2149: @cindex Vax calling convention
        !          2150: @cindex Ultrix calling convention
        !          2151: @item
        !          2152: On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
        !          2153: by function calls.  However, the C compiler uses conventions compatible
        !          2154: with BSD Unix: registers 2 through 5 may be clobbered by function calls.
        !          2155: 
        !          2156: GNU CC uses the same convention as the Ultrix C compiler.  You can use
        !          2157: these options to produce code compatible with the Fortran compiler:
        !          2158: 
        !          2159: @smallexample
        !          2160: -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
        !          2161: @end smallexample
        !          2162: 
        !          2163: @item
        !          2164: @cindex DBX
        !          2165: DBX rejects some files produced by GNU CC, though it accepts similar
        !          2166: constructs in output from PCC.  Until someone can supply a coherent
        !          2167: description of what is valid DBX input and what is not, there is
        !          2168: nothing I can do about these problems.  You are on your own.
        !          2169: @end itemize
        !          2170: 
        !          2171: @include extend.texi
        !          2172: 
        !          2173: @node Bugs, VMS, Extensions, Top
        !          2174: @chapter Reporting Bugs
        !          2175: @cindex bugs
        !          2176: @cindex reporting bugs
        !          2177: 
        !          2178: Your bug reports play an essential role in making GNU CC reliable.
        !          2179: 
        !          2180: When you encounter a problem, the first thing to do is to see if it is
        !          2181: already known.  @xref{Trouble}.  Also look in @ref{Incompatibilities}.
        !          2182: If it isn't known, then you should report the problem.
        !          2183: 
        !          2184: Reporting a bug may help you by bringing a solution to your problem, or
        !          2185: it may not.  (If it does not, look in the service directory; see
        !          2186: @ref{Service}.)  In any case, the principal function of a bug report is
        !          2187: to help the entire community by making the next version of GNU CC work
        !          2188: better.  Bug reports are your contribution to the maintenance of GNU CC.
        !          2189: 
        !          2190: In order for a bug report to serve its purpose, you must include the
        !          2191: information that makes for fixing the bug.
        !          2192: 
        !          2193: @menu
        !          2194: * Criteria:  Bug Criteria.   Have you really found a bug?
        !          2195: * Reporting: Bug Reporting.  How to report a bug effectively.
        !          2196: * Non-bugs::                 Some things we think are not problems.
        !          2197: * Known: Trouble.            Known problems.
        !          2198: * Help: Service.             Where to ask for help.
        !          2199: @end menu
        !          2200: 
        !          2201: @node Bug Criteria, Bug Reporting, Bugs, Bugs
        !          2202: @section Have You Found a Bug?
        !          2203: @cindex bug criteria
        !          2204: 
        !          2205: If you are not sure whether you have found a bug, here are some guidelines:
        !          2206: 
        !          2207: @itemize @bullet
        !          2208: @cindex fatal signal
        !          2209: @cindex core dump
        !          2210: @item
        !          2211: If the compiler gets a fatal signal, for any input whatever, that is a
        !          2212: compiler bug.  Reliable compilers never crash.
        !          2213: 
        !          2214: @cindex invalid assembly code
        !          2215: @cindex assembly code, invalid
        !          2216: @item
        !          2217: If the compiler produces invalid assembly code, for any input whatever
        !          2218: (except an @code{asm} statement), that is a compiler bug, unless the
        !          2219: compiler reports errors (not just warnings) which would ordinarily
        !          2220: prevent the assembler from being run.
        !          2221: 
        !          2222: @cindex undefined behavior
        !          2223: @cindex undefined function value
        !          2224: @cindex increment operators
        !          2225: @item
        !          2226: If the compiler produces valid assembly code that does not correctly
        !          2227: execute the input source code, that is a compiler bug.
        !          2228: 
        !          2229: However, you must double-check to make sure, because you may have run
        !          2230: into an incompatibility between GNU C and traditional C
        !          2231: (@pxref{Incompatibilities}).  These incompatibilities might be considered
        !          2232: bugs, but they are inescapable consequences of valuable features.
        !          2233: 
        !          2234: Or you may have a program whose behavior is undefined, which happened
        !          2235: by chance to give the desired results with another C compiler.
        !          2236: 
        !          2237: For example, in many nonoptimizing compilers, you can write @samp{x;}
        !          2238: at the end of a function instead of @samp{return x;}, with the same
        !          2239: results.  But the value of the function is undefined if @code{return}
        !          2240: is omitted; it is not a bug when GNU CC produces different results.
        !          2241: 
        !          2242: Problems often result from expressions with two increment operators,
        !          2243: as in @code{f (*p++, *p++)}.  Your previous compiler might have
        !          2244: interpreted that expression the way you intended; GNU CC might
        !          2245: interpret it another way.  Neither compiler is wrong.  The bug is
        !          2246: in your code.
        !          2247: 
        !          2248: After you have localized the error to a single source line, it should
        !          2249: be easy to check for these things.  If your program is correct and
        !          2250: well defined, you have found a compiler bug.
        !          2251: 
        !          2252: @item
        !          2253: If the compiler produces an error message for valid input, that is a
        !          2254: compiler bug.
        !          2255: 
        !          2256: Note that the following is not valid input, and the error message for
        !          2257: it is not a bug:
        !          2258: 
        !          2259: @example
        !          2260: int foo (char);
        !          2261: 
        !          2262: int
        !          2263: foo (x)
        !          2264:      char x;
        !          2265: @{ @dots{} @}
        !          2266: @end example
        !          2267: 
        !          2268: @noindent
        !          2269: The prototype says to pass a @code{char}, while the definition says to
        !          2270: pass an @code{int} and treat the value as a @code{char}.  This is what
        !          2271: the ANSI standard says, and it makes sense.
        !          2272: 
        !          2273: @cindex invalid input
        !          2274: @item
        !          2275: If the compiler does not produce an error message for invalid input,
        !          2276: that is a compiler bug.  However, you should note that your idea of
        !          2277: ``invalid input'' might be my idea of ``an extension'' or ``support
        !          2278: for traditional practice''.
        !          2279: 
        !          2280: @item
        !          2281: If you are an experienced user of C compilers, your suggestions
        !          2282: for improvement of GNU CC are welcome in any case.
        !          2283: @end itemize
        !          2284: 
        !          2285: @node Bug Reporting, Non-bugs, Bug Criteria, Bugs
        !          2286: @section How to Report Bugs
        !          2287: @cindex bug reports
        !          2288: @cindex compiler bugs, reporting
        !          2289: 
        !          2290: Send bug reports for GNU C to one of these addresses:
        !          2291: 
        !          2292: @example
        !          2293: bug-gcc@@prep.ai.mit.edu
        !          2294: @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gcc
        !          2295: @end example
        !          2296: 
        !          2297: @strong{Do not send bug reports to @samp{help-gcc}, or to the newsgroup
        !          2298: @samp{gnu.gcc.help}.} Most users of GNU CC do not want to receive bug
        !          2299: reports.  Those that do, have asked to be on @samp{bug-gcc}.
        !          2300: 
        !          2301: The mailing list @samp{bug-gcc} has a newsgroup which serves as a
        !          2302: repeater.  The mailing list and the newsgroup carry exactly the same
        !          2303: messages.  Often people think of posting bug reports to the newsgroup
        !          2304: instead of mailing them.  This appears to work, but it has one problem
        !          2305: which can be crucial: a newsgroup posting does not contain a mail path
        !          2306: back to the sender.  Thus, if I need to ask for more information, I
        !          2307: may be unable to reach you.  For this reason, it is better to send bug
        !          2308: reports to the mailing list.
        !          2309: 
        !          2310: As a last resort, send bug reports on paper to:
        !          2311: 
        !          2312: @example
        !          2313: GNU Compiler Bugs
        !          2314: Free Software Foundation
        !          2315: 675 Mass Ave
        !          2316: Cambridge, MA 02139
        !          2317: @end example
        !          2318: 
        !          2319: The fundamental principle of reporting bugs usefully is this:
        !          2320: @strong{report all the facts}.  If you are not sure whether to state a
        !          2321: fact or leave it out, state it!
        !          2322: 
        !          2323: Often people omit facts because they think they know what causes the
        !          2324: problem and they conclude that some details don't matter.  Thus, you might
        !          2325: assume that the name of the variable you use in an example does not matter.
        !          2326: Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
        !          2327: stray memory reference which happens to fetch from the location where that
        !          2328: name is stored in memory; perhaps, if the name were different, the contents
        !          2329: of that location would fool the compiler into doing the right thing despite
        !          2330: the bug.  Play it safe and give a specific, complete example.  That is the
        !          2331: easiest thing for you to do, and the most helpful.
        !          2332: 
        !          2333: Keep in mind that the purpose of a bug report is to enable me to fix
        !          2334: the bug if it is not known.  It isn't very important what happens if
        !          2335: the bug is already known.  Therefore, always write your bug reports on
        !          2336: the assumption that the bug is not known.
        !          2337: 
        !          2338: Sometimes people give a few sketchy facts and ask, ``Does this ring a
        !          2339: bell?''  Those bug reports are useless, and I urge everyone to
        !          2340: @emph{refuse to respond to them} except to chide the sender to report
        !          2341: bugs properly.
        !          2342: 
        !          2343: To enable me to fix the bug, you should include all these things:
        !          2344: 
        !          2345: @itemize @bullet
        !          2346: @item
        !          2347: The version of GNU CC.  You can get this by running it with the
        !          2348: @samp{-v} option.
        !          2349: 
        !          2350: Without this, I won't know whether there is any point in looking for
        !          2351: the bug in the current version of GNU CC.
        !          2352: 
        !          2353: @item
        !          2354: A complete input file that will reproduce the bug.  If the bug is in
        !          2355: the C preprocessor, send me a source file and any header files that it
        !          2356: requires.  If the bug is in the compiler proper (@file{cc1}), run your
        !          2357: source file through the C preprocessor by doing @samp{gcc -E
        !          2358: @var{sourcefile} > @var{outfile}}, then include the contents of
        !          2359: @var{outfile} in the bug report.  (Any @samp{-I}, @samp{-D} or
        !          2360: @samp{-U} options that you used in actual compilation should also be
        !          2361: used when doing this.)
        !          2362: 
        !          2363: A single statement is not enough of an example.  In order to compile
        !          2364: it, it must be embedded in a function definition; and the bug might
        !          2365: depend on the details of how this is done.
        !          2366: 
        !          2367: Without a real example I can compile, all I can do about your bug
        !          2368: report is wish you luck.  It would be futile to try to guess how to
        !          2369: provoke the bug.  For example, bugs in register allocation and
        !          2370: reloading frequently depend on every little detail of the function
        !          2371: they happen in.
        !          2372: 
        !          2373: @item
        !          2374: The command arguments you gave GNU CC to compile that example and
        !          2375: observe the bug.  For example, did you use @samp{-O}?  To guarantee
        !          2376: you won't omit something important, list them all.
        !          2377: 
        !          2378: If I were to try to guess the arguments, I would probably guess wrong
        !          2379: and then I would not encounter the bug.
        !          2380: 
        !          2381: @item
        !          2382: The type of machine you are using, and the operating system name and
        !          2383: version number.
        !          2384: 
        !          2385: @item
        !          2386: The operands you gave to the @code{configure} command when you installed
        !          2387: the compiler.
        !          2388: 
        !          2389: @item
        !          2390: A description of what behavior you observe that you believe is
        !          2391: incorrect.  For example, ``It gets a fatal signal,'' or, ``There is an
        !          2392: incorrect assembler instruction in the output.''
        !          2393: 
        !          2394: Of course, if the bug is that the compiler gets a fatal signal, then I
        !          2395: will certainly notice it.  But if the bug is incorrect output, I might
        !          2396: not notice unless it is glaringly wrong.  I won't study all the
        !          2397: assembler code from a 50-line C program just on the off chance that it
        !          2398: might be wrong.
        !          2399: 
        !          2400: Even if the problem you experience is a fatal signal, you should still
        !          2401: say so explicitly.  Suppose something strange is going on, such as,
        !          2402: your copy of the compiler is out of synch, or you have encountered a
        !          2403: bug in the C library on your system.  (This has happened!)  Your copy
        !          2404: might crash and mine would not.  If you @i{told} me to expect a crash,
        !          2405: then when mine fails to crash, I would know that the bug was not
        !          2406: happening for me.  If you had not told me to expect a crash, then I
        !          2407: would not be able to draw any conclusion from my observations.
        !          2408: 
        !          2409: Often the observed symptom is incorrect output when your program is run.
        !          2410: Sad to say, this is not enough information for me unless the program is
        !          2411: short and simple.  If you send me a large program, I don't have time to
        !          2412: figure out how it would work if compiled correctly, much less which line
        !          2413: of it was compiled wrong.  So you will have to do that.  Tell me which
        !          2414: source line it is, and what incorrect result happens when that line is
        !          2415: executed.  A person who understands the program can find this as
        !          2416: easily as a bug in the program itself.
        !          2417: 
        !          2418: @item
        !          2419: If you send me examples of output from GNU CC, please use @samp{-g}
        !          2420: when you make them.  The debugging information includes source line
        !          2421: numbers which are essential for correlating the output with the input.
        !          2422: 
        !          2423: @item
        !          2424: If you wish to suggest changes to the GNU CC source, send me context
        !          2425: diffs.  If you even discuss something in the GNU CC source, refer to
        !          2426: it by context, not by line number.
        !          2427: 
        !          2428: The line numbers in my development sources don't match those in your
        !          2429: sources.  Your line numbers would convey no useful information to me.
        !          2430: 
        !          2431: @item
        !          2432: Additional information from a debugger might enable me to find
        !          2433: a problem on a machine which I do not have available myself.
        !          2434: However, you need to think when you collect this information if
        !          2435: you want it to have any chance of being useful.
        !          2436: 
        !          2437: @cindex backtrace for bug reports
        !          2438: For example, many people send just a backtrace, but that is never
        !          2439: useful by itself.  A simple backtrace with arguments conveys little
        !          2440: about GNU CC because the compiler is largely data-driven; the same
        !          2441: functions are called over and over for different RTL insns, doing
        !          2442: different things depending on the details of the insn.
        !          2443: 
        !          2444: Most of the arguments listed in the backtrace are useless because they
        !          2445: are pointers to RTL list structure.  The numeric values of the
        !          2446: pointers, which the debugger prints in the backtrace, have no
        !          2447: significance whatever; all that matters is the contents of the objects
        !          2448: they point to (and most of the contents are other such pointers).
        !          2449: 
        !          2450: In addition, most compiler passes consist of one or more loops that
        !          2451: scan the RTL insn sequence.  The most vital piece of information about
        !          2452: such a loop---which insn it has reached---is usually in a local variable,
        !          2453: not in an argument.
        !          2454: 
        !          2455: @findex debug_rtx
        !          2456: What you need to provide in addition to a backtrace are the values of
        !          2457: the local variables for several stack frames up.  When a local
        !          2458: variable or an argument is an RTX, first print its value and then use
        !          2459: the GDB command @code{pr} to print the RTL expression that it points
        !          2460: to.  (If GDB doesn't run on your machine, use your debugger to call
        !          2461: the function @code{debug_rtx} with the RTX as an argument.)  In
        !          2462: general, whenever a variable is a pointer, its value is no use
        !          2463: without the data it points to.
        !          2464: 
        !          2465: In addition, include a debugging dump from just before the pass
        !          2466: in which the crash happens.  Most bugs involve a series of insns,
        !          2467: not just one.
        !          2468: @end itemize
        !          2469: 
        !          2470: Here are some things that are not necessary:
        !          2471: 
        !          2472: @itemize @bullet
        !          2473: @item
        !          2474: A description of the envelope of the bug.
        !          2475: 
        !          2476: Often people who encounter a bug spend a lot of time investigating
        !          2477: which changes to the input file will make the bug go away and which
        !          2478: changes will not affect it.
        !          2479: 
        !          2480: This is often time consuming and not very useful, because the way I
        !          2481: will find the bug is by running a single example under the debugger
        !          2482: with breakpoints, not by pure deduction from a series of examples.
        !          2483: I recommend that you save your time for something else.
        !          2484: 
        !          2485: Of course, if you can find a simpler example to report @emph{instead}
        !          2486: of the original one, that is a convenience for me.  Errors in the
        !          2487: output will be easier to spot, running under the debugger will take
        !          2488: less time, etc.  Most GNU CC bugs involve just one function, so the
        !          2489: most straightforward way to simplify an example is to delete all the
        !          2490: function definitions except the one where the bug occurs.  Those
        !          2491: earlier in the file may be replaced by external declarations if the
        !          2492: crucial function depends on them.  (Exception: inline functions may
        !          2493: affect compilation of functions defined later in the file.)
        !          2494: 
        !          2495: However, simplification is not vital; if you don't want to do this,
        !          2496: report the bug anyway and send me the entire test case you used.
        !          2497: 
        !          2498: @item
        !          2499: A patch for the bug.
        !          2500: 
        !          2501: A patch for the bug does help me if it is a good one.  But don't omit
        !          2502: the necessary information, such as the test case, on the assumption that
        !          2503: a patch is all I need.  I might see problems with your patch and decide
        !          2504: to fix the problem another way, or I might not understand it at all.
        !          2505: 
        !          2506: Sometimes with a program as complicated as GNU CC it is very hard to
        !          2507: construct an example that will make the program follow a certain path
        !          2508: through the code.  If you don't send me the example, I won't be able
        !          2509: to construct one, so I won't be able to verify that the bug is fixed.
        !          2510: 
        !          2511: And if I can't understand what bug you are trying to fix, or why your
        !          2512: patch should be an improvement, I won't install it.  A test case will
        !          2513: help me to understand.
        !          2514: 
        !          2515: @item
        !          2516: A guess about what the bug is or what it depends on.
        !          2517: 
        !          2518: Such guesses are usually wrong.  Even I can't guess right about such
        !          2519: things without first using the debugger to find the facts.
        !          2520: @end itemize
        !          2521: 
        !          2522: @node Non-bugs,, Bug Reporting, Bugs
        !          2523: @section Certain Changes We Don't Want to Make
        !          2524: 
        !          2525: This section lists changes that people frequently request, but which
        !          2526: we do not make because we think GNU CC is better without them.
        !          2527: 
        !          2528: @itemize @bullet
        !          2529: @item 
        !          2530: Checking the number and type of arguments to a function which has an
        !          2531: old-fashioned definition and no prototype.
        !          2532: 
        !          2533: Such a feature would work only occasionally---only for calls that appear
        !          2534: in the same file as the called function, following the definition.  The
        !          2535: only way to check all calls reliably is to add a prototype for the
        !          2536: function.  But adding a prototype will eliminate the need for this
        !          2537: feature.  So the feature is not worthwhile.
        !          2538: 
        !          2539: @item 
        !          2540: Warning about using an expression whose type is signed as a shift count.
        !          2541: 
        !          2542: Shift count operands are probably signed more often than unsigned.
        !          2543: Warning about this would cause far more annoyance than good.
        !          2544: 
        !          2545: @item
        !          2546: Warning about assigning a signed value to an unsigned variable.
        !          2547: 
        !          2548: Such assignments must be very common; warning about them would cause
        !          2549: more annoyance than good.
        !          2550: 
        !          2551: @item
        !          2552: Making bitfields unsigned by default on particular machines where ``the
        !          2553: ABI standard'' says to do so.
        !          2554: 
        !          2555: The ANSI C standard leaves it up to the implementation whether a bitfield
        !          2556: declared plain @code{int} is signed or not.  This in effect creates two
        !          2557: alternative dialects of C.
        !          2558: 
        !          2559: The GNU C compiler supports both dialects; you can specify the dialect
        !          2560: you want with the option @samp{-fsigned-bitfields} or
        !          2561: @samp{-funsigned-bitfields}.  However, this leaves open the question
        !          2562: of which dialect to use by default.
        !          2563: 
        !          2564: Currently, the preferred dialect makes plain bitfields signed, because
        !          2565: this is simplest.  Since @code{int} is the same as @code{signed int} in
        !          2566: every other context, it is cleanest for them to be the same in bitfields
        !          2567: as well.
        !          2568: 
        !          2569: Some computer manufacturers have published Application Binary Interface
        !          2570: standards which specify that plain bitfields should be unsigned.  It is
        !          2571: a mistake, however, to say anything about this issue in an ABI.  This is
        !          2572: because the handling of plain bitfields distinguishes two dialects of C.
        !          2573: Both dialects are meaningful on every type of machine.  Whether a
        !          2574: particular object file was compiled using signed bitfields or unsigned
        !          2575: is of no concern to functions in any other object file, even if they
        !          2576: access the same bitfields in the same data structures.
        !          2577: 
        !          2578: A given program is written in one or the other of these two dialects.
        !          2579: The program stands a chance to work on most any machine if it is
        !          2580: compiled with the proper dialect.  It is unlikely to work at all if
        !          2581: compiled with the wrong dialect.
        !          2582: 
        !          2583: Many users appreciate the GNU C compiler because it provides an
        !          2584: environment that is uniform across machines.  These users would be
        !          2585: inconvenienced if the compiler treated plain bitfields differently on
        !          2586: certain machines.
        !          2587: 
        !          2588: Occasionally users write programs intended only for a particular machine
        !          2589: type.  On these occasions, the users would benefit if the GNU C compiler
        !          2590: were to support by default the same dialect as the other compilers on
        !          2591: that machine.  But such applications are rare.  And users writing a
        !          2592: program to run on more than one type of machine cannot possibly benefit
        !          2593: from this kind of compatibility.
        !          2594: 
        !          2595: This is why GNU CC does and will treat plain bitfields in the same
        !          2596: fashion on all types of machines (by default).
        !          2597: 
        !          2598: (Of course, users strongly concerned about portability should indicate
        !          2599: explicitly in each bitfield whether it is signed or not.)
        !          2600: 
        !          2601: @item
        !          2602: Undefining @code{__STDC__} when @samp{-ansi} is not used.
        !          2603: 
        !          2604: Currently, GNU CC defines @code{__STDC__} as long as you don't use
        !          2605: @samp{-traditional}.  This provides good results in practice.
        !          2606: 
        !          2607: Programmers normally use conditionals on @code{__STDC__} to ask whether
        !          2608: it is safe to use certain features of ANSI C, such as function
        !          2609: prototypes or ANSI token concatenation.  Since plain @samp{gcc} supports
        !          2610: all the features of ANSI C, the correct answer to these questions is
        !          2611: ``yes''.
        !          2612: 
        !          2613: Some users try to use @code{__STDC__} to check for the availability of
        !          2614: certain library facilities.  This is actually incorrect usage in an ANSI
        !          2615: C program, because the ANSI C standard says that a conforming
        !          2616: freestanding implementation should define @code{__STDC__} even though it
        !          2617: does not have the library facilities.  @samp{gcc -ansi -pedantic} is a
        !          2618: conforming freestanding implementation, and it is therefore required to
        !          2619: define @code{__STDC__}, even though it does not come with an ANSI C
        !          2620: library.
        !          2621: 
        !          2622: Sometimes people say that defining @code{__STDC__} in a compiler that
        !          2623: does not completely conform to the ANSI C standard somehow violates the
        !          2624: standard.  This is illogical.  The standard is a standard for compilers
        !          2625: that are supposed to conform.  It says nothing about what any other
        !          2626: compilers should do.  Whatever the ANSI C standard says is relevant to
        !          2627: the design of plain @samp{gcc} without @samp{-ansi} only for pragmatic
        !          2628: reasons, not as a requirement.
        !          2629: 
        !          2630: @item
        !          2631: Undefining @code{__STDC__} in C++.
        !          2632: 
        !          2633: Programs written to compile with C++-to-C translators get the
        !          2634: value of @code{__STDC__} that goes with the C compiler that is
        !          2635: subsequently used.  These programs must test @code{__STDC__}
        !          2636: to determine what kind of C preprocessor that compiler uses:
        !          2637: whether they should concatenate tokens in the ANSI C fashion
        !          2638: or in the traditional fashion.
        !          2639: 
        !          2640: These programs work properly with GNU C++ if @code{__STDC__} is defined.
        !          2641: They would not work otherwise.
        !          2642: 
        !          2643: In addition, many header files are written to provide prototypes in ANSI
        !          2644: C but not in traditional C.  Many of these header files can work without
        !          2645: change in C++ provided @code{__STDC__} is defined.  If @code{__STDC__}
        !          2646: is not defined, they will all fail, and will all need to be changed to
        !          2647: test explicitly for C++ as well.
        !          2648: @end itemize
        !          2649: 
        !          2650: @ifset INTERNALS
        !          2651: @node VMS, Portability, Bugs, Top
        !          2652: @chapter Using GNU CC on VMS
        !          2653: @end ifset
        !          2654: @ifclear INTERNALS
        !          2655: @node VMS, Index, Bugs, Top
        !          2656: @chapter Using GNU CC on VMS
        !          2657: @end ifclear
        !          2658: 
        !          2659: @menu
        !          2660: * Include Files and VMS::  Where the preprocessor looks for the include files.
        !          2661: * Global Declarations::    How to do globaldef, globalref and globalvalue with
        !          2662:                            GNU CC.
        !          2663: * VMS Misc::              Misc information.
        !          2664: @end menu
        !          2665: 
        !          2666: @node Include Files and VMS, Global Declarations, VMS, VMS 
        !          2667: @section Include Files and VMS
        !          2668: 
        !          2669: @cindex include files and VMS
        !          2670: @cindex VMS and include files
        !          2671: @cindex header files and VMS
        !          2672: Due to the differences between the filesystems of Unix and VMS, GNU CC
        !          2673: attempts to translate file names in @samp{#include} into names that VMS
        !          2674: will understand.  The basic strategy is to prepend a prefix to the
        !          2675: specification of the include file, convert the whole filename to a VMS
        !          2676: filename, and then try to open the file.  GNU CC tries various prefixes
        !          2677: one by one until one of them succeeds:
        !          2678: 
        !          2679: @enumerate
        !          2680: @item
        !          2681: The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
        !          2682: where GNU C header files are traditionally stored.  If you wish to store
        !          2683: header files in non-standard locations, then you can assign the logical
        !          2684: @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
        !          2685: list is suitable for use with a rooted logical.
        !          2686: 
        !          2687: @item
        !          2688: The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}.  This is where
        !          2689: VAX-C header files are traditionally stored.
        !          2690: 
        !          2691: @item 
        !          2692: If the include file specification by itself is a valid VMS filename, the
        !          2693: preprocessor then uses this name with no prefix in an attempt to open
        !          2694: the include file.
        !          2695: 
        !          2696: @item
        !          2697: If the file specification is not a valid VMS filename (i.e. does not
        !          2698: contain a device or a directory specifier, and contains a @samp{/}
        !          2699: character), the preprocessor tries to convert it from Unix syntax to 
        !          2700: VMS syntax.
        !          2701: 
        !          2702: Conversion works like this: the first directory name becomes a device,
        !          2703: and the rest of the directories are converted into VMS-format directory
        !          2704: names.  For example, @file{X11/foobar.h} is translated to
        !          2705: @file{X11:[000000]foobar.h} or @file{X11:foobar.h}, whichever one can be
        !          2706: opened.  This strategy allows you to assign a logical name to point to
        !          2707: the actual location of the header files.
        !          2708: 
        !          2709: @item
        !          2710: If none of these strategies succeeds, the @samp{#include} fails.
        !          2711: @end enumerate
        !          2712: 
        !          2713: Include directives of the form:
        !          2714: 
        !          2715: @example
        !          2716: #include foobar
        !          2717: @end example
        !          2718: 
        !          2719: @noindent
        !          2720: are a common source of incompatibility between VAX-C and GNU CC.  VAX-C
        !          2721: treats this much like a standard @code{#include <foobar.h>} directive.
        !          2722: That is incompatible with the ANSI C behavior implemented by GNU CC: to
        !          2723: expand the name @code{foobar} as a macro.  Macro expansion should
        !          2724: eventually yield one of the two standard formats for @code{#include}:
        !          2725: 
        !          2726: @example
        !          2727: #include "@var{file}"
        !          2728: #include <@var{file}>
        !          2729: @end example
        !          2730: 
        !          2731: If you have this problem, the best solution is to modify the source to
        !          2732: convert the @code{#include} directives to one of the two standard forms.
        !          2733: That will work with either compiler.  If you want a quick and dirty fix,
        !          2734: define the file names as macros with the proper expansion, like this:
        !          2735: 
        !          2736: @example
        !          2737: #define stdio <stdio.h>
        !          2738: @end example
        !          2739: 
        !          2740: @noindent
        !          2741: This will work, as long as the name doesn't conflict with anything else
        !          2742: in the program.
        !          2743: 
        !          2744: Another source of incompatibility is that VAX-C assumes that:
        !          2745: 
        !          2746: @example
        !          2747: #include "foobar"
        !          2748: @end example
        !          2749: 
        !          2750: @noindent
        !          2751: is actually asking for the file @file{foobar.h}.  GNU CC does not
        !          2752: make this assumption, and instead takes what you ask for literally;
        !          2753: it tries to read the file @file{foobar}.  The best way to avoid this
        !          2754: problem is to always specify the desired file extension in your include
        !          2755: directives.
        !          2756: 
        !          2757: GNU CC for VMS is distributed with a set of include files that is
        !          2758: sufficient to compile most general purpose programs.  Even though the
        !          2759: GNU CC distribution does not contain header files to define constants
        !          2760: and structures for some VMS system-specific functions, there is no
        !          2761: reason why you cannot use GNU CC with any of these functions.  You first
        !          2762: may have to generate or create header files, either by using the public
        !          2763: domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
        !          2764: extracting the relevant modules from one of the system macro libraries,
        !          2765: and using an editor to construct a C header file.
        !          2766: 
        !          2767: @node Global Declarations, VMS Misc, Include Files and VMS, VMS
        !          2768: @section Global Declarations and VMS
        !          2769: 
        !          2770: @findex GLOBALREF
        !          2771: @findex GLOBALDEF
        !          2772: @findex GLOBALVALUEDEF
        !          2773: @findex GLOBALVALUEREF
        !          2774: GNU CC does not provide the @code{globalref}, @code{globaldef} and
        !          2775: @code{globalvalue} keywords of VAX-C.  You can get the same effect with
        !          2776: an obscure feature of GAS, the GNU assembler.  (This requires GAS
        !          2777: version 1.39 or later.)  The following macros allow you to use this
        !          2778: feature in a fairly natural way:
        !          2779: 
        !          2780: @smallexample
        !          2781: #ifdef __GNUC__
        !          2782: #define GLOBALREF(NAME) \
        !          2783:         NAME asm("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME  )
        !          2784: #define GLOBALDEF(NAME,VALUE) \
        !          2785:         NAME asm("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME  ) = VALUE
        !          2786: #define GLOBALVALUEREF(NAME) \
        !          2787:   const NAME [1] asm("_$$PsectAttributes_GLOBALVALUE$$" #NAME  )
        !          2788: #define GLOBALVALUEDEF(NAME,VALUE) \
        !          2789:   const NAME [1] asm("_$$PsectAttributes_GLOBALVALUE$$" #NAME  ) = @{VALUE@}
        !          2790: #else
        !          2791: #define GLOBALREF(NAME) globalref NAME
        !          2792: #define GLOBALDEF(NAME,VALUE) globaldef NAME = VALUE
        !          2793: #define GLOBALVALUEDEF(NAME,VALUE) globalvalue NAME = VALUE
        !          2794: #define GLOBALVALUEREF(NAME) globalvalue NAME
        !          2795: #endif
        !          2796: @end smallexample
        !          2797: 
        !          2798: @noindent
        !          2799: (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
        !          2800: name is removed by the assembler, after it has modified the attributes
        !          2801: of the symbol).  These macros are provided in the VMS binaries
        !          2802: distribution in a header file @file{GNU_HACKS.H}.  An example of the
        !          2803: usage is:
        !          2804: 
        !          2805: @example
        !          2806: int GLOBALREF (ijk);
        !          2807: int GLOBALDEF (jkl, 0);
        !          2808: @end example
        !          2809: 
        !          2810: The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
        !          2811: straightforwardly for arrays, since there is no way to insert the array
        !          2812: dimension into the declaration at the right place.  However, you can
        !          2813: declare an array with these macros if you first define a typedef for the
        !          2814: array type, like this:
        !          2815: 
        !          2816: @example
        !          2817: typedef int intvector[10];
        !          2818: intvector GLOBALREF (foo);
        !          2819: @end example
        !          2820: 
        !          2821: Array and structure initializers will also break the macros; you can
        !          2822: define the initializer to be a macro of its own, or you can expand the
        !          2823: @code{GLOBALDEF} macro by hand.  You may find a case where you wish to
        !          2824: use the @code{GLOBALDEF} macro with a large array, but you are not
        !          2825: interested in explicitly initializing each element of the array.  In
        !          2826: such cases you can use an initializer like: @code{@{0,@}}, which will
        !          2827: initialize the entire array to @code{0}.
        !          2828: 
        !          2829: A shortcoming of this implementation is that a variable declared with
        !          2830: @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array.  For
        !          2831: example, the declaration:
        !          2832: 
        !          2833: @example
        !          2834: int GLOBALVALUEREF(ijk);
        !          2835: @end example
        !          2836: 
        !          2837: @noindent
        !          2838: declares the variable @code{ijk} as an array of type @code{int [1]}.
        !          2839: This is done because a globalvalue is actually a constant; its ``value''
        !          2840: is what the linker would normally consider an address.  That is not how
        !          2841: an integer value works in C, but it is how an array works.  So treating
        !          2842: the symbol as an array name gives consistent results---with the
        !          2843: exception that the value seems to have the wrong type.  @strong{Don't
        !          2844: try to access an element of the array.}  It doesn't have any elements.
        !          2845: The array ``address'' may not be the address of actual storage.
        !          2846: 
        !          2847: The fact that the symbol is an array may lead to warnings where the
        !          2848: variable is used.  Insert type casts to avoid the warnings.  Here is an
        !          2849: example; it takes advantage of the ANSI C feature allowing macros that
        !          2850: expand to use the same name as the macro itself.
        !          2851: 
        !          2852: @example
        !          2853: int GLOBALVALUEREF (ss$_normal);
        !          2854: int GLOBALVALUEDEF (xyzzy,123);
        !          2855: #ifdef __GNUC__
        !          2856: #define ss$_normal ((int) ss$_normal)
        !          2857: #define xyzzy ((int) xyzzy)
        !          2858: #endif
        !          2859: @end example
        !          2860: 
        !          2861: Don't use @code{globaldef} or @code{globalref} with a variable whose
        !          2862: type is an enumeration type; this is not implemented.  Instead, make the
        !          2863: variable an integer, and use a @code{globalvaluedef} for each of the
        !          2864: enumeration values.  An example of this would be:
        !          2865: 
        !          2866: @example
        !          2867: #ifdef __GNUC__
        !          2868: int GLOBALDEF (color, 0);
        !          2869: int GLOBALVALUEDEF (RED, 0);
        !          2870: int GLOBALVALUEDEF (BLUE, 1);
        !          2871: int GLOBALVALUEDEF (GREEN, 3);
        !          2872: #else
        !          2873: enum globaldef color @{RED, BLUE, GREEN = 3@};
        !          2874: #endif
        !          2875: @end example
        !          2876: 
        !          2877: @node VMS Misc, , Global Declarations, VMS
        !          2878: @section Other VMS Issues
        !          2879: 
        !          2880: @cindex exit status and VMS
        !          2881: @cindex return value of @code{main}
        !          2882: @cindex @code{main} and the exit status
        !          2883: GNU CC automatically arranges for @code{main} to return 1 by default if
        !          2884: you fail to specify an explicit return value.  This will be interpreted
        !          2885: by VMS as a status code indicating a normal successful completion.
        !          2886: Version 1 of GNU CC did not provide this default.
        !          2887: 
        !          2888: GNU CC on VMS works only with the GNU assembler, GAS.  You need version
        !          2889: 1.37 or later of GAS in order to produce value debugging information for
        !          2890: the VMS debugger.  Use the ordinary VMS linker with the object files
        !          2891: produced by GAS.
        !          2892: 
        !          2893: @cindex shared VMS run time system
        !          2894: @cindex @file{VAXCRTL}
        !          2895: Under previous versions of GNU CC, the generated code would occasionally
        !          2896: give strange results when linked to the sharable @file{VAXCRTL} library.
        !          2897: Now this should work.
        !          2898: 
        !          2899: A caveat for use of @code{const} global variables: the @code{const}
        !          2900: modifier must be specified in every external declaration of the variable
        !          2901: in all of the source files that use that variable.  Otherwise the linker
        !          2902: will issue warnings about conflicting attributes for the variable.  Your
        !          2903: program will still work despite the warnings, but the variable will be
        !          2904: placed in writable storage.
        !          2905: 
        !          2906: @cindex name augmentation
        !          2907: @cindex case sensitivity and VMS
        !          2908: @cindex VMS and case sensitivity
        !          2909: The VMS linker does not distinguish between upper and lower case letters
        !          2910: in function and variable names.  However, usual practice in C is to
        !          2911: distinguish case.  Normally GNU CC (by means of the assembler GAS)
        !          2912: implements usual C behavior by augmenting each name that is not all
        !          2913: lower-case.  A name is augmented by truncating it to at most 23
        !          2914: characters and then adding more characters at the end which encode the
        !          2915: case pattern the rest.
        !          2916: 
        !          2917: Name augmentation yields bad results for programs that use precompiled
        !          2918: libraries (such as Xlib) which were generated by another compiler.  You
        !          2919: can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
        !          2920: it makes external C functions and variables case-independent as is usual
        !          2921: on VMS.  Alternatively, you could write all references to the functions
        !          2922: and variables in such libraries using lower case; this will work on VMS,
        !          2923: but is not portable to other systems.
        !          2924: 
        !          2925: Function and variable names are handled somewhat differently with GNU
        !          2926: C++.  The GNU C++ compiler performs @dfn{name mangling} on function
        !          2927: names, which means that it adds information to the function name to
        !          2928: describe the data types of the arguments that the function takes. One
        !          2929: result of this is that the name of a function can become very long.
        !          2930: Since the VMS linker only recognizes the first 31 characters in a name,
        !          2931: special action is taken to ensure that each function and variable has a
        !          2932: unique name that can be represented in 31 characters.
        !          2933: 
        !          2934: If the name (plus a name augmentation, if required) is less than 32
        !          2935: characters in length, then no special action is performed. If the name
        !          2936: is longer than 31 characters, the assembler (GAS) will generate a
        !          2937: hash string based upon the function name, truncate the function name to
        !          2938: 23 characters, and append the hash string to the truncated name.  If the
        !          2939: @samp{/VERBOSE} compiler option is used, the assembler will print both
        !          2940: the full and truncated names of each symbol that is truncated.
        !          2941: 
        !          2942: The @samp{/NOCASE_HACK} compiler option should not be used when you are
        !          2943: compiling programs that use libg++. libg++ has several instances of
        !          2944: objects (i.e.  @code{Filebuf} and @code{filebuf}) which become
        !          2945: indistinguishable in a case-insensitive environment.  This leads to
        !          2946: cases where you need to inhibit augmentation selectively (if you were
        !          2947: using libg++ and Xlib in the same program, for example).  There is no
        !          2948: special feature for doing this, but you can get the result by defining a
        !          2949: macro for each mixed case symbol for which you wish to inhibit
        !          2950: augmentation.  The macro should expand into the lower case equivalent of
        !          2951: itself.  For example:
        !          2952: 
        !          2953: @example
        !          2954: #define StuDlyCapS studlycaps
        !          2955: @end example
        !          2956: 
        !          2957: These macro definitions can be placed in a header file to minimize the
        !          2958: number of changes to your source code.
        !          2959: 
        !          2960: @ifset INTERNALS
        !          2961: @node Portability, Interface, VMS, Top
        !          2962: @chapter GNU CC and Portability
        !          2963: @cindex portability
        !          2964: @cindex GNU CC and portability
        !          2965: 
        !          2966: The main goal of GNU CC was to make a good, fast compiler for machines in
        !          2967: the class that the GNU system aims to run on: 32-bit machines that address
        !          2968: 8-bit bytes and have several general registers.  Elegance, theoretical
        !          2969: power and simplicity are only secondary.
        !          2970: 
        !          2971: GNU CC gets most of the information about the target machine from a machine
        !          2972: description which gives an algebraic formula for each of the machine's
        !          2973: instructions.  This is a very clean way to describe the target.  But when
        !          2974: the compiler needs information that is difficult to express in this
        !          2975: fashion, I have not hesitated to define an ad-hoc parameter to the machine
        !          2976: description.  The purpose of portability is to reduce the total work needed
        !          2977: on the compiler; it was not of interest for its own sake.
        !          2978: 
        !          2979: @cindex endianness
        !          2980: @cindex autoincrement addressing, availability
        !          2981: @findex abort
        !          2982: GNU CC does not contain machine dependent code, but it does contain code
        !          2983: that depends on machine parameters such as endianness (whether the most
        !          2984: significant byte has the highest or lowest address of the bytes in a word)
        !          2985: and the availability of autoincrement addressing.  In the RTL-generation
        !          2986: pass, it is often necessary to have multiple strategies for generating code
        !          2987: for a particular kind of syntax tree, strategies that are usable for different
        !          2988: combinations of parameters.  Often I have not tried to address all possible
        !          2989: cases, but only the common ones or only the ones that I have encountered.
        !          2990: As a result, a new target may require additional strategies.  You will know
        !          2991: if this happens because the compiler will call @code{abort}.  Fortunately,
        !          2992: the new strategies can be added in a machine-independent fashion, and will
        !          2993: affect only the target machines that need them.
        !          2994: @end ifset
        !          2995: 
        !          2996: @ifset INTERNALS
        !          2997: @node Interface, Passes, Portability, Top
        !          2998: @chapter Interfacing to GNU CC Output
        !          2999: @cindex interfacing to GNU CC output
        !          3000: @cindex run-time conventions
        !          3001: @cindex function call conventions
        !          3002: @cindex conventions, run-time
        !          3003: 
        !          3004: GNU CC is normally configured to use the same function calling convention
        !          3005: normally in use on the target system.  This is done with the
        !          3006: machine-description macros described (@pxref{Machine Macros}).
        !          3007: 
        !          3008: @cindex unions, returning
        !          3009: @cindex structures, returning
        !          3010: @cindex returning structures and unions
        !          3011: However, returning of structure and union values is done differently on
        !          3012: some target machines.  As a result, functions compiled with PCC
        !          3013: returning such types cannot be called from code compiled with GNU CC,
        !          3014: and vice versa.  This does not cause trouble often because few Unix
        !          3015: library routines return structures or unions.
        !          3016: 
        !          3017: GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes
        !          3018: long in the same registers used for @code{int} or @code{double} return
        !          3019: values.  (GNU CC typically allocates variables of such types in
        !          3020: registers also.)  Structures and unions of other sizes are returned by
        !          3021: storing them into an address passed by the caller (usually in a
        !          3022: register).  The machine-description macros @code{STRUCT_VALUE} and
        !          3023: @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address.
        !          3024: 
        !          3025: By contrast, PCC on most target machines returns structures and unions
        !          3026: of any size by copying the data into an area of static storage, and then
        !          3027: returning the address of that storage as if it were a pointer value.
        !          3028: The caller must copy the data from that memory area to the place where
        !          3029: the value is wanted.  This is slower than the method used by GNU CC, and
        !          3030: fails to be reentrant.
        !          3031: 
        !          3032: On some target machines, such as RISC machines and the 80386, the
        !          3033: standard system convention is to pass to the subroutine the address of
        !          3034: where to return the value.  On these machines, GNU CC has been
        !          3035: configured to be compatible with the standard compiler, when this method
        !          3036: is used.  It may not be compatible for structures of 1, 2, 4 or 8 bytes.
        !          3037: 
        !          3038: @cindex argument passing
        !          3039: @cindex passing arguments
        !          3040: GNU CC uses the system's standard convention for passing arguments.  On
        !          3041: some machines, the first few arguments are passed in registers; in
        !          3042: others, all are passed on the stack.  It would be possible to use
        !          3043: registers for argument passing on any machine, and this would probably
        !          3044: result in a significant speedup.  But the result would be complete
        !          3045: incompatibility with code that follows the standard convention.  So this
        !          3046: change is practical only if you are switching to GNU CC as the sole C
        !          3047: compiler for the system.  We may implement register argument passing on
        !          3048: certain machines once we have a complete GNU system so that we can
        !          3049: compile the libraries with GNU CC.
        !          3050: 
        !          3051: On some machines (particularly the Sparc), certain types of arguments
        !          3052: are passed ``by invisible reference''.  This means that the value is
        !          3053: stored in memory, and the address of the memory location is passed to
        !          3054: the subroutine.
        !          3055: 
        !          3056: @cindex @code{longjmp} and automatic variables
        !          3057: If you use @code{longjmp}, beware of automatic variables.  ANSI C says that
        !          3058: automatic variables that are not declared @code{volatile} have undefined
        !          3059: values after a @code{longjmp}.  And this is all GNU CC promises to do,
        !          3060: because it is very difficult to restore register variables correctly, and
        !          3061: one of GNU CC's features is that it can put variables in registers without
        !          3062: your asking it to.
        !          3063: 
        !          3064: If you want a variable to be unaltered by @code{longjmp}, and you don't
        !          3065: want to write @code{volatile} because old C compilers don't accept it,
        !          3066: just take the address of the variable.  If a variable's address is ever
        !          3067: taken, even if just to compute it and ignore it, then the variable cannot
        !          3068: go in a register:
        !          3069: 
        !          3070: @example
        !          3071: @{
        !          3072:   int careful;
        !          3073:   &careful;
        !          3074:   @dots{}
        !          3075: @}
        !          3076: @end example
        !          3077: 
        !          3078: @cindex arithmetic libraries
        !          3079: @cindex math libraries
        !          3080: Code compiled with GNU CC may call certain library routines.  Most of
        !          3081: them handle arithmetic for which there are no instructions.  This
        !          3082: includes multiply and divide on some machines, and floating point
        !          3083: operations on any machine for which floating point support is disabled
        !          3084: with @samp{-msoft-float}.  Some standard parts of the C library, such as
        !          3085: @code{bcopy} or @code{memcpy}, are also called automatically.  The usual
        !          3086: function call interface is used for calling the library routines.
        !          3087: 
        !          3088: These library routines should be defined in the library @file{libgcc.a},
        !          3089: which GNU CC automatically searches whenever it links a program.  On
        !          3090: machines that have multiply and divide instructions, if hardware
        !          3091: floating point is in use, normally @file{libgcc.a} is not needed, but it
        !          3092: is searched just in case.
        !          3093: 
        !          3094: Each arithmetic function is defined in @file{libgcc1.c} to use the
        !          3095: corresponding C arithmetic operator.  As long as the file is compiled
        !          3096: with another C compiler, which supports all the C arithmetic operators,
        !          3097: this file will work portably.  However, @file{libgcc1.c} does not work if
        !          3098: compiled with GNU CC, because each arithmetic function would compile
        !          3099: into a call to itself!
        !          3100: @end ifset
        !          3101: 
        !          3102: @ifset INTERNALS
        !          3103: @node Passes, RTL, Interface, Top
        !          3104: @chapter Passes and Files of the Compiler
        !          3105: @cindex passes and files of the compiler
        !          3106: @cindex files and passes of the compiler
        !          3107: @cindex compiler passes and files
        !          3108: 
        !          3109: @cindex top level of compiler
        !          3110: The overall control structure of the compiler is in @file{toplev.c}.  This
        !          3111: file is responsible for initialization, decoding arguments, opening and
        !          3112: closing files, and sequencing the passes.
        !          3113: 
        !          3114: @cindex parsing pass
        !          3115: The parsing pass is invoked only once, to parse the entire input.  The RTL
        !          3116: intermediate code for a function is generated as the function is parsed, a
        !          3117: statement at a time.  Each statement is read in as a syntax tree and then
        !          3118: converted to RTL; then the storage for the tree for the statement is
        !          3119: reclaimed.  Storage for types (and the expressions for their sizes),
        !          3120: declarations, and a representation of the binding contours and how they nest,
        !          3121: remain until the function is finished being compiled; these are all needed
        !          3122: to output the debugging information.
        !          3123: 
        !          3124: @findex rest_of_compilation
        !          3125: @findex rest_of_decl_compilation
        !          3126: Each time the parsing pass reads a complete function definition or
        !          3127: top-level declaration, it calls the function
        !          3128: @code{rest_of_compilation} or @code{rest_of_decl_compilation} in
        !          3129: @file{toplev.c}, which are responsible for all further processing
        !          3130: necessary, ending with output of the assembler language.  All other
        !          3131: compiler passes run, in sequence, within @code{rest_of_compilation}.
        !          3132: When that function returns from compiling a function definition, the
        !          3133: storage used for that function definition's compilation is entirely
        !          3134: freed, unless it is an inline function (@pxref{Inline}).
        !          3135: 
        !          3136: Here is a list of all the passes of the compiler and their source files.
        !          3137: Also included is a description of where debugging dumps can be requested
        !          3138: with @samp{-d} options.
        !          3139: 
        !          3140: @itemize @bullet
        !          3141: @item
        !          3142: Parsing.  This pass reads the entire text of a function definition,
        !          3143: constructing partial syntax trees.  This and RTL generation are no longer
        !          3144: truly separate passes (formerly they were), but it is easier to think
        !          3145: of them as separate.
        !          3146: 
        !          3147: The tree representation does not entirely follow C syntax, because it is
        !          3148: intended to support other languages as well.
        !          3149: 
        !          3150: Language-specific data type analysis is also done in this pass, and every
        !          3151: tree node that represents an expression has a data type attached.
        !          3152: Variables are represented as declaration nodes.
        !          3153: 
        !          3154: @cindex constant folding
        !          3155: @cindex arithmetic simplifications
        !          3156: @cindex simplifications, arithmetic
        !          3157: Constant folding and some arithmetic simplifications are also done
        !          3158: during this pass.
        !          3159: 
        !          3160: The language-independent source files for parsing are
        !          3161: @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
        !          3162: There are also header files @file{tree.h} and @file{tree.def}
        !          3163: which define the format of the tree representation.@refill
        !          3164: 
        !          3165: The source files for parsing C are @file{c-parse.y}, @file{c-decl.c},
        !          3166: @file{c-typeck.c}, @file{c-convert.c}, @file{c-lang.c}, and
        !          3167: @file{c-aux-info.c} along with header files @file{c-lex.h}, and
        !          3168: @file{c-tree.h}.
        !          3169: 
        !          3170: The source files for parsing C++ are @file{cp-parse.y},
        !          3171: @file{cp-class.c}, @file{cp-cvt.c},@*
        !          3172: @file{cp-decl.c}, @file{cp-decl.c}, @file{cp-decl2.c},
        !          3173: @file{cp-dem.c}, @file{cp-except.c},@*
        !          3174: @file{cp-expr.c}, @file{cp-init.c}, @file{cp-lex.c},
        !          3175: @file{cp-method.c}, @file{cp-ptree.c},@*
        !          3176: @file{cp-search.c}, @file{cp-tree.c}, @file{cp-type2.c}, and
        !          3177: @file{cp-typeck.c}, along with header files @file{cp-tree.def},
        !          3178: @file{cp-tree.h}, and @file{cp-decl.h}.
        !          3179: 
        !          3180: The special source files for parsing Objective C are
        !          3181: @file{objc-parse.y}, @file{objc-actions.c}, @file{objc-tree.def}, and
        !          3182: @file{objc-actions.h}.  Certain C-specific files are used for this as
        !          3183: well.
        !          3184: 
        !          3185: The file @file{c-common.c} is also used for all of the above languages.
        !          3186: 
        !          3187: @cindex RTL generation
        !          3188: @item
        !          3189: RTL generation.  This is the conversion of syntax tree into RTL code.
        !          3190: It is actually done statement-by-statement during parsing, but for
        !          3191: most purposes it can be thought of as a separate pass.
        !          3192: 
        !          3193: @cindex target-parameter-dependent code
        !          3194: This is where the bulk of target-parameter-dependent code is found,
        !          3195: since often it is necessary for strategies to apply only when certain
        !          3196: standard kinds of instructions are available.  The purpose of named
        !          3197: instruction patterns is to provide this information to the RTL
        !          3198: generation pass.
        !          3199: 
        !          3200: @cindex tail recursion optimization
        !          3201: Optimization is done in this pass for @code{if}-conditions that are
        !          3202: comparisons, boolean operations or conditional expressions.  Tail
        !          3203: recursion is detected at this time also.  Decisions are made about how
        !          3204: best to arrange loops and how to output @code{switch} statements.
        !          3205: 
        !          3206: The source files for RTL generation include @file{stmt.c},
        !          3207: @file{function.c}, @file{expr.c}, @file{calls.c}, @file{explow.c},
        !          3208: @file{expmed.c}, @file{optabs.c} and @file{emit-rtl.c}.  Also, the file
        !          3209: @file{insn-emit.c}, generated from the machine description by the
        !          3210: program @code{genemit}, is used in this pass.  The header file
        !          3211: @file{expr.h} is used for communication within this pass.@refill
        !          3212: 
        !          3213: @findex genflags
        !          3214: @findex gencodes
        !          3215: The header files @file{insn-flags.h} and @file{insn-codes.h},
        !          3216: generated from the machine description by the programs @code{genflags}
        !          3217: and @code{gencodes}, tell this pass which standard names are available
        !          3218: for use and which patterns correspond to them.@refill
        !          3219: 
        !          3220: Aside from debugging information output, none of the following passes
        !          3221: refers to the tree structure representation of the function (only
        !          3222: part of which is saved).
        !          3223: 
        !          3224: @cindex inline, automatic
        !          3225: The decision of whether the function can and should be expanded inline
        !          3226: in its subsequent callers is made at the end of rtl generation.  The
        !          3227: function must meet certain criteria, currently related to the size of
        !          3228: the function and the types and number of parameters it has.  Note that
        !          3229: this function may contain loops, recursive calls to itself
        !          3230: (tail-recursive functions can be inlined!), gotos, in short, all
        !          3231: constructs supported by GNU CC.  The file @file{integrate.c} contains
        !          3232: the code to save a function's rtl for later inlining and to inline that
        !          3233: rtl when the function is called.  The header file @file{integrate.h}
        !          3234: is also used for this purpose.
        !          3235: 
        !          3236: The option @samp{-dr} causes a debugging dump of the RTL code after
        !          3237: this pass.  This dump file's name is made by appending @samp{.rtl} to
        !          3238: the input file name.
        !          3239: 
        !          3240: @cindex jump optimization
        !          3241: @cindex unreachable code
        !          3242: @cindex dead code
        !          3243: @item
        !          3244: Jump optimization.  This pass simplifies jumps to the following
        !          3245: instruction, jumps across jumps, and jumps to jumps.  It deletes
        !          3246: unreferenced labels and unreachable code, except that unreachable code
        !          3247: that contains a loop is not recognized as unreachable in this pass.
        !          3248: (Such loops are deleted later in the basic block analysis.)  It also
        !          3249: converts some code originally written with jumps into sequences of
        !          3250: instructions that directly set values from the results of comparisons,
        !          3251: if the machine has such instructions.
        !          3252: 
        !          3253: Jump optimization is performed two or three times.  The first time is
        !          3254: immediately following RTL generation.  The second time is after CSE,
        !          3255: but only if CSE says repeated jump optimization is needed.  The
        !          3256: last time is right before the final pass.  That time, cross-jumping
        !          3257: and deletion of no-op move instructions are done together with the
        !          3258: optimizations described above.
        !          3259: 
        !          3260: The source file of this pass is @file{jump.c}.
        !          3261: 
        !          3262: The option @samp{-dj} causes a debugging dump of the RTL code after
        !          3263: this pass is run for the first time.  This dump file's name is made by
        !          3264: appending @samp{.jump} to the input file name.
        !          3265: 
        !          3266: @cindex register use analysis
        !          3267: @item
        !          3268: Register scan.  This pass finds the first and last use of each
        !          3269: register, as a guide for common subexpression elimination.  Its source
        !          3270: is in @file{regclass.c}.
        !          3271: 
        !          3272: @cindex jump threading
        !          3273: @item
        !          3274: Jump threading.  This pass detects a condition jump that branches to an
        !          3275: identical or inverse test.  Such jumps can be @samp{threaded} through
        !          3276: the second conditional test.  The source code for this pass is in
        !          3277: @file{jump.c}.  This optimization is only performed if
        !          3278: @samp{-fthread-jumps} is enabled.
        !          3279: 
        !          3280: @cindex common subexpression elimination
        !          3281: @cindex constant propagation
        !          3282: @item
        !          3283: Common subexpression elimination.  This pass also does constant
        !          3284: propagation.  Its source file is @file{cse.c}.  If constant
        !          3285: propagation causes conditional jumps to become unconditional or to
        !          3286: become no-ops, jump optimization is run again when CSE is finished.
        !          3287: 
        !          3288: The option @samp{-ds} causes a debugging dump of the RTL code after
        !          3289: this pass.  This dump file's name is made by appending @samp{.cse} to
        !          3290: the input file name.
        !          3291: 
        !          3292: @cindex loop optimization
        !          3293: @cindex code motion
        !          3294: @cindex strength-reduction
        !          3295: @item
        !          3296: Loop optimization.  This pass moves constant expressions out of loops,
        !          3297: and optionally does strength-reduction and loop unrolling as well.
        !          3298: Its source files are @file{loop.c} and @file{unroll.c}, plus the header
        !          3299: @file{loop.h} used for communication between them.  Loop unrolling uses
        !          3300: some functions in @file{integrate.c} and the header @file{integrate.h}.
        !          3301: 
        !          3302: The option @samp{-dL} causes a debugging dump of the RTL code after
        !          3303: this pass.  This dump file's name is made by appending @samp{.loop} to
        !          3304: the input file name.
        !          3305: 
        !          3306: @item
        !          3307: If @samp{-frerun-cse-after-loop} was enabled, a second common
        !          3308: subexpression elimination pass is performed after the loop optimization
        !          3309: pass.  Jump threading is also done again at this time if it was specified.
        !          3310: 
        !          3311: The option @samp{-dt} causes a debugging dump of the RTL code after
        !          3312: this pass.  This dump file's name is made by appending @samp{.cse2} to
        !          3313: the input file name.
        !          3314: 
        !          3315: @cindex register allocation, stupid
        !          3316: @cindex stupid register allocation
        !          3317: @item
        !          3318: Stupid register allocation is performed at this point in a
        !          3319: nonoptimizing compilation.  It does a little data flow analysis as
        !          3320: well.  When stupid register allocation is in use, the next pass
        !          3321: executed is the reloading pass; the others in between are skipped.
        !          3322: The source file is @file{stupid.c}.
        !          3323: 
        !          3324: @cindex data flow analysis
        !          3325: @cindex analysis, data flow
        !          3326: @cindex basic blocks
        !          3327: @item
        !          3328: Data flow analysis (@file{flow.c}).  This pass divides the program
        !          3329: into basic blocks (and in the process deletes unreachable loops); then
        !          3330: it computes which pseudo-registers are live at each point in the
        !          3331: program, and makes the first instruction that uses a value point at
        !          3332: the instruction that computed the value.
        !          3333: 
        !          3334: @cindex autoincrement/decrement analysis
        !          3335: This pass also deletes computations whose results are never used, and
        !          3336: combines memory references with add or subtract instructions to make
        !          3337: autoincrement or autodecrement addressing.
        !          3338: 
        !          3339: The option @samp{-df} causes a debugging dump of the RTL code after
        !          3340: this pass.  This dump file's name is made by appending @samp{.flow} to
        !          3341: the input file name.  If stupid register allocation is in use, this
        !          3342: dump file reflects the full results of such allocation.
        !          3343: 
        !          3344: @cindex instruction combination
        !          3345: @item
        !          3346: Instruction combination (@file{combine.c}).  This pass attempts to
        !          3347: combine groups of two or three instructions that are related by data
        !          3348: flow into single instructions.  It combines the RTL expressions for
        !          3349: the instructions by substitution, simplifies the result using algebra,
        !          3350: and then attempts to match the result against the machine description.
        !          3351: 
        !          3352: The option @samp{-dc} causes a debugging dump of the RTL code after
        !          3353: this pass.  This dump file's name is made by appending @samp{.combine}
        !          3354: to the input file name.
        !          3355: 
        !          3356: @cindex instruction scheduling
        !          3357: @cindex scheduling, instruction
        !          3358: @item
        !          3359: Instruction scheduling (@file{sched.c}).  This pass looks for
        !          3360: instructions whose output will not be available by the time that it is
        !          3361: used in subsequent instructions.  (Memory loads and floating point
        !          3362: instructions often have this behavior on RISC machines).  It re-orders
        !          3363: instructions within a basic block to try to separate the definition and
        !          3364: use of items that otherwise would cause pipeline stalls.
        !          3365: 
        !          3366: Instruction scheduling is performed twice.  The first time is immediately
        !          3367: after instruction combination and the second is immediately after reload.
        !          3368: 
        !          3369: The option @samp{-dS} causes a debugging dump of the RTL code after this
        !          3370: pass is run for the first time.  The dump file's name is made by
        !          3371: appending @samp{.sched} to the input file name.
        !          3372: 
        !          3373: @cindex register class preference pass
        !          3374: @item
        !          3375: Register class preferencing.  The RTL code is scanned to find out
        !          3376: which register class is best for each pseudo register.  The source
        !          3377: file is @file{regclass.c}.
        !          3378: 
        !          3379: @cindex register allocation
        !          3380: @cindex local register allocation
        !          3381: @item
        !          3382: Local register allocation (@file{local-alloc.c}).  This pass allocates
        !          3383: hard registers to pseudo registers that are used only within one basic
        !          3384: block.  Because the basic block is linear, it can use fast and
        !          3385: powerful techniques to do a very good job.
        !          3386: 
        !          3387: The option @samp{-dl} causes a debugging dump of the RTL code after
        !          3388: this pass.  This dump file's name is made by appending @samp{.lreg} to
        !          3389: the input file name.
        !          3390: 
        !          3391: @cindex global register allocation
        !          3392: @item
        !          3393: Global register allocation (@file{global-alloc.c}).  This pass
        !          3394: allocates hard registers for the remaining pseudo registers (those
        !          3395: whose life spans are not contained in one basic block).
        !          3396: 
        !          3397: @cindex reloading
        !          3398: @item
        !          3399: Reloading.  This pass renumbers pseudo registers with the hardware
        !          3400: registers numbers they were allocated.  Pseudo registers that did not
        !          3401: get hard registers are replaced with stack slots.  Then it finds
        !          3402: instructions that are invalid because a value has failed to end up in
        !          3403: a register, or has ended up in a register of the wrong kind.  It fixes
        !          3404: up these instructions by reloading the problematical values
        !          3405: temporarily into registers.  Additional instructions are generated to
        !          3406: do the copying.
        !          3407: 
        !          3408: The reload pass also optionally eliminates the frame pointer and inserts
        !          3409: instructions to save and restore call-clobbered registers around calls.
        !          3410: 
        !          3411: Source files are @file{reload.c} and @file{reload1.c}, plus the header
        !          3412: @file{reload.h} used for communication between them.
        !          3413: 
        !          3414: The option @samp{-dg} causes a debugging dump of the RTL code after
        !          3415: this pass.  This dump file's name is made by appending @samp{.greg} to
        !          3416: the input file name.
        !          3417: 
        !          3418: @cindex instruction scheduling
        !          3419: @cindex scheduling, instruction
        !          3420: @item
        !          3421: Instruction scheduling is repeated here to try to avoid pipeline stalls
        !          3422: due to memory loads generated for spilled pseudo registers.
        !          3423: 
        !          3424: The option @samp{-dR} causes a debugging dump of the RTL code after
        !          3425: this pass.  This dump file's name is made by appending @samp{.sched2}
        !          3426: to the input file name.
        !          3427: 
        !          3428: @cindex cross-jumping
        !          3429: @cindex no-op move instructions
        !          3430: @item
        !          3431: Jump optimization is repeated, this time including cross-jumping
        !          3432: and deletion of no-op move instructions.
        !          3433: 
        !          3434: The option @samp{-dJ} causes a debugging dump of the RTL code after
        !          3435: this pass.  This dump file's name is made by appending @samp{.jump2}
        !          3436: to the input file name.
        !          3437: 
        !          3438: @cindex delayed branch scheduling
        !          3439: @cindex scheduling, delayed branch
        !          3440: @item
        !          3441: Delayed branch scheduling.  This optional pass attempts to find
        !          3442: instructions that can go into the delay slots of other instructions,
        !          3443: usually jumps and calls.  The source file name is @file{reorg.c}.  
        !          3444: 
        !          3445: The option @samp{-dd} causes a debugging dump of the RTL code after
        !          3446: this pass.  This dump file's name is made by appending @samp{.dbr}
        !          3447: to the input file name.
        !          3448: 
        !          3449: @cindex register-to-stack conversion
        !          3450: @item
        !          3451: Conversion from usage of some hard registers to usage of a register
        !          3452: stack may be done at this point.  Currently, this is supported only
        !          3453: for the floating-point registers of the Intel 80387 coprocessor.   The
        !          3454: source file name is @file{reg-stack.c}.
        !          3455: 
        !          3456: The options @samp{-dk} causes a debugging dump of the RTL code after
        !          3457: this pass.  This dump file's name is made by appending @samp{.stack}
        !          3458: to the input file name.
        !          3459: 
        !          3460: @cindex final pass
        !          3461: @cindex peephole optimization
        !          3462: @item
        !          3463: Final.  This pass outputs the assembler code for the function.  It is
        !          3464: also responsible for identifying spurious test and compare
        !          3465: instructions.  Machine-specific peephole optimizations are performed
        !          3466: at the same time.  The function entry and exit sequences are generated
        !          3467: directly as assembler code in this pass; they never exist as RTL.
        !          3468: 
        !          3469: The source files are @file{final.c} plus @file{insn-output.c}; the
        !          3470: latter is generated automatically from the machine description by the
        !          3471: tool @file{genoutput}.  The header file @file{conditions.h} is used
        !          3472: for communication between these files.
        !          3473: 
        !          3474: @cindex debugging information generation
        !          3475: @item
        !          3476: Debugging information output.  This is run after final because it must
        !          3477: output the stack slot offsets for pseudo registers that did not get
        !          3478: hard registers.  Source files are @file{dbxout.c} for DBX symbol table
        !          3479: format, @file{sdbout.c} for SDB symbol table format, and
        !          3480: @file{dwarfout.c} for DWARF symbol table format.
        !          3481: @end itemize
        !          3482: 
        !          3483: Some additional files are used by all or many passes:
        !          3484: 
        !          3485: @itemize @bullet
        !          3486: @item
        !          3487: Every pass uses @file{machmode.def} and @file{machmode.h} which define
        !          3488: the machine modes.
        !          3489: 
        !          3490: @item
        !          3491: Several passes use @file{real.h}, which defines the default
        !          3492: representation of floating point constants and how to operate on them.
        !          3493: 
        !          3494: @item
        !          3495: All the passes that work with RTL use the header files @file{rtl.h}
        !          3496: and @file{rtl.def}, and subroutines in file @file{rtl.c}.  The tools
        !          3497: @code{gen*} also use these files to read and work with the machine
        !          3498: description RTL.
        !          3499: 
        !          3500: @findex genconfig
        !          3501: @item
        !          3502: Several passes refer to the header file @file{insn-config.h} which
        !          3503: contains a few parameters (C macro definitions) generated
        !          3504: automatically from the machine description RTL by the tool
        !          3505: @code{genconfig}.
        !          3506: 
        !          3507: @cindex instruction recognizer
        !          3508: @item
        !          3509: Several passes use the instruction recognizer, which consists of
        !          3510: @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
        !          3511: and @file{insn-extract.c} that are generated automatically from the
        !          3512: machine description by the tools @file{genrecog} and
        !          3513: @file{genextract}.@refill
        !          3514: 
        !          3515: @item
        !          3516: Several passes use the header files @file{regs.h} which defines the
        !          3517: information recorded about pseudo register usage, and @file{basic-block.h}
        !          3518: which defines the information recorded about basic blocks.
        !          3519: 
        !          3520: @item
        !          3521: @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
        !          3522: with a bit for each hard register, and some macros to manipulate it.
        !          3523: This type is just @code{int} if the machine has few enough hard registers;
        !          3524: otherwise it is an array of @code{int} and some of the macros expand
        !          3525: into loops.
        !          3526: 
        !          3527: @item
        !          3528: Several passes use instruction attributes.  A definition of the
        !          3529: attributes defined for a particular machine is in file
        !          3530: @file{insn-attr.h}, which is generated from the machine description by
        !          3531: the program @file{genattr}.  The file @file{insn-attrtab.c} contains
        !          3532: subroutines to obtain the attribute values for insns.  It is generated
        !          3533: from the machine description by the program @file{genattrtab}.@refill
        !          3534: @end itemize
        !          3535: @end ifset
        !          3536: 
        !          3537: @include rtl.texi
        !          3538: @include md.texi
        !          3539: @include tm.texi
        !          3540: 
        !          3541: @ifset INTERNALS
        !          3542: @node Config, Index, Machine Macros, Top
        !          3543: @chapter The Configuration File
        !          3544: @cindex configuration file
        !          3545: @cindex @file{xm-@var{machine}.h}
        !          3546: 
        !          3547: The configuration file @file{xm-@var{machine}.h} contains macro
        !          3548: definitions that describe the machine and system on which the compiler
        !          3549: is running, unlike the definitions in @file{@var{machine}.h}, which
        !          3550: describe the machine for which the compiler is producing output.  Most
        !          3551: of the values in @file{xm-@var{machine}.h} are actually the same on all
        !          3552: machines that GNU CC runs on, so large parts of all configuration files
        !          3553: are identical.  But there are some macros that vary:
        !          3554: 
        !          3555: @table @code
        !          3556: @findex USG
        !          3557: @item USG
        !          3558: Define this macro if the host system is System V.
        !          3559: 
        !          3560: @findex VMS
        !          3561: @item VMS
        !          3562: Define this macro if the host system is VMS.
        !          3563: 
        !          3564: @findex FAILURE_EXIT_CODE
        !          3565: @item FAILURE_EXIT_CODE
        !          3566: A C expression for the status code to be returned when the compiler
        !          3567: exits after serious errors.
        !          3568: 
        !          3569: @findex SUCCESS_EXIT_CODE
        !          3570: @item SUCCESS_EXIT_CODE
        !          3571: A C expression for the status code to be returned when the compiler
        !          3572: exits without serious errors.
        !          3573: 
        !          3574: @findex HOST_WORDS_BIG_ENDIAN
        !          3575: @item HOST_WORDS_BIG_ENDIAN
        !          3576: Defined if the host machine stores words of multi-word values in
        !          3577: big-endian order.  (GNU CC does not depend on the host byte ordering
        !          3578: within a word.)
        !          3579: 
        !          3580: @findex HOST_FLOAT_FORMAT
        !          3581: @item HOST_FLOAT_FORMAT
        !          3582: A numeric code distinguishing the floating point format for the host
        !          3583: machine.  See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
        !          3584: alternatives and default.
        !          3585: 
        !          3586: @findex HOST_BITS_PER_CHAR
        !          3587: @item HOST_BITS_PER_CHAR
        !          3588: A C expression for the number of bits in @code{char} on the host
        !          3589: machine.
        !          3590: 
        !          3591: @findex HOST_BITS_PER_SHORT
        !          3592: @item HOST_BITS_PER_SHORT
        !          3593: A C expression for the number of bits in @code{short} on the host
        !          3594: machine.
        !          3595: 
        !          3596: @findex HOST_BITS_PER_INT
        !          3597: @item HOST_BITS_PER_INT
        !          3598: A C expression for the number of bits in @code{int} on the host
        !          3599: machine.
        !          3600: 
        !          3601: @findex HOST_BITS_PER_LONG
        !          3602: @item HOST_BITS_PER_LONG
        !          3603: A C expression for the number of bits in @code{long} on the host
        !          3604: machine.
        !          3605: 
        !          3606: @findex ONLY_INT_FIELDS
        !          3607: @item ONLY_INT_FIELDS
        !          3608: Define this macro to indicate that the host compiler only supports
        !          3609: @code{int} bit fields, rather than other integral types, including
        !          3610: @code{enum}, as do most C compilers.
        !          3611: 
        !          3612: @findex EXECUTABLE_SUFFIX
        !          3613: @item EXECUTABLE_SUFFIX
        !          3614: Define this macro if the host system uses a naming convention for
        !          3615: executable files that involves a common suffix (such as, in some
        !          3616: systems, @samp{.exe}) that must be mentioned explicitly when you run
        !          3617: the program.
        !          3618: 
        !          3619: @findex OBSTACK_CHUNK_SIZE
        !          3620: @item OBSTACK_CHUNK_SIZE
        !          3621: A C expression for the size of ordinary obstack chunks.
        !          3622: If you don't define this, a usually-reasonable default is used.
        !          3623: 
        !          3624: @findex OBSTACK_CHUNK_ALLOC
        !          3625: @item OBSTACK_CHUNK_ALLOC
        !          3626: The function used to allocate obstack chunks.
        !          3627: If you don't define this, @code{xmalloc} is used.
        !          3628: 
        !          3629: @findex OBSTACK_CHUNK_FREE
        !          3630: @item OBSTACK_CHUNK_FREE
        !          3631: The function used to free obstack chunks.
        !          3632: If you don't define this, @code{free} is used.
        !          3633: 
        !          3634: @findex USE_C_ALLOCA
        !          3635: @item USE_C_ALLOCA
        !          3636: Define this macro to indicate that the compiler is running with the
        !          3637: @code{alloca} implemented in C.  This version of @code{alloca} can be
        !          3638: found in the file @file{alloca.c}; to use it, you must also alter the
        !          3639: @file{Makefile} variable @code{ALLOCA}.  (This is done automatically
        !          3640: for the systems on which we know it is needed.)
        !          3641: 
        !          3642: If you do define this macro, you should probably do it as follows:
        !          3643: 
        !          3644: @example
        !          3645: #ifndef __GNUC__
        !          3646: #define USE_C_ALLOCA
        !          3647: #else
        !          3648: #define alloca __builtin_alloca
        !          3649: #endif
        !          3650: @end example
        !          3651: 
        !          3652: @noindent
        !          3653: so that when the compiler is compiled with GNU CC it uses the more
        !          3654: efficient built-in @code{alloca} function.
        !          3655: 
        !          3656: @item FUNCTION_CONVERSION_BUG
        !          3657: @findex FUNCTION_CONVERSION_BUG
        !          3658: Define this macro to indicate that the host compiler does not properly
        !          3659: handle converting a function value to a pointer-to-function when it is
        !          3660: used in an expression.
        !          3661: @end table
        !          3662: 
        !          3663: @findex bzero
        !          3664: @findex bcmp
        !          3665: In addition, configuration files for system V define @code{bcopy},
        !          3666: @code{bzero} and @code{bcmp} as aliases.  Some files define @code{alloca}
        !          3667: as a macro when compiled with GNU CC, in order to take advantage of the
        !          3668: benefit of GNU CC's built-in @code{alloca}.
        !          3669: 
        !          3670: 
        !          3671: @node Index,, Config, Top
        !          3672: @unnumbered Index
        !          3673: @end ifset
        !          3674: 
        !          3675: @ifclear INTERNALS
        !          3676: @node Index,, VMS, Top
        !          3677: @unnumbered Index
        !          3678: @end ifclear
        !          3679: 
        !          3680: @printindex cp
        !          3681: @contents
        !          3682: @bye

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