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