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