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