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