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