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