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