1 | This is Info file gcc.info, produced by Makeinfo version 1.67 from the |
---|
2 | input file gcc.texi. |
---|
3 | |
---|
4 | This file documents the use and the internals of the GNU compiler. |
---|
5 | |
---|
6 | Published by the Free Software Foundation 59 Temple Place - Suite 330 |
---|
7 | Boston, MA 02111-1307 USA |
---|
8 | |
---|
9 | Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998 |
---|
10 | Free Software Foundation, Inc. |
---|
11 | |
---|
12 | Permission is granted to make and distribute verbatim copies of this |
---|
13 | manual provided the copyright notice and this permission notice are |
---|
14 | preserved on all copies. |
---|
15 | |
---|
16 | Permission is granted to copy and distribute modified versions of |
---|
17 | this manual under the conditions for verbatim copying, provided also |
---|
18 | that the sections entitled "GNU General Public License," "Funding for |
---|
19 | Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are |
---|
20 | included exactly as in the original, and provided that the entire |
---|
21 | resulting derived work is distributed under the terms of a permission |
---|
22 | notice identical to this one. |
---|
23 | |
---|
24 | Permission is granted to copy and distribute translations of this |
---|
25 | manual into another language, under the above conditions for modified |
---|
26 | versions, except that the sections entitled "GNU General Public |
---|
27 | License," "Funding for Free Software," and "Protect Your Freedom--Fight |
---|
28 | `Look And Feel'", and this permission notice, may be included in |
---|
29 | translations approved by the Free Software Foundation instead of in the |
---|
30 | original English. |
---|
31 | |
---|
32 | |
---|
33 | File: gcc.info, Node: Bug Reporting, Next: Sending Patches, Prev: Bug Lists, Up: Bugs |
---|
34 | |
---|
35 | How to Report Bugs |
---|
36 | ================== |
---|
37 | |
---|
38 | The fundamental principle of reporting bugs usefully is this: |
---|
39 | *report all the facts*. If you are not sure whether to state a fact or |
---|
40 | leave it out, state it! |
---|
41 | |
---|
42 | Often people omit facts because they think they know what causes the |
---|
43 | problem and they conclude that some details don't matter. Thus, you |
---|
44 | might assume that the name of the variable you use in an example does |
---|
45 | not matter. Well, probably it doesn't, but one cannot be sure. |
---|
46 | Perhaps the bug is a stray memory reference which happens to fetch from |
---|
47 | the location where that name is stored in memory; perhaps, if the name |
---|
48 | were different, the contents of that location would fool the compiler |
---|
49 | into doing the right thing despite the bug. Play it safe and give a |
---|
50 | specific, complete example. That is the easiest thing for you to do, |
---|
51 | and the most helpful. |
---|
52 | |
---|
53 | Keep in mind that the purpose of a bug report is to enable someone to |
---|
54 | fix the bug if it is not known. It isn't very important what happens if |
---|
55 | the bug is already known. Therefore, always write your bug reports on |
---|
56 | the assumption that the bug is not known. |
---|
57 | |
---|
58 | Sometimes people give a few sketchy facts and ask, "Does this ring a |
---|
59 | bell?" This cannot help us fix a bug, so it is basically useless. We |
---|
60 | respond by asking for enough details to enable us to investigate. You |
---|
61 | might as well expedite matters by sending them to begin with. |
---|
62 | |
---|
63 | Try to make your bug report self-contained. If we have to ask you |
---|
64 | for more information, it is best if you include all the previous |
---|
65 | information in your response, as well as the information that was |
---|
66 | missing. |
---|
67 | |
---|
68 | Please report each bug in a separate message. This makes it easier |
---|
69 | for us to track which bugs have been fixed and to forward your bugs |
---|
70 | reports to the appropriate maintainer. |
---|
71 | |
---|
72 | Do not compress and encode any part of your bug report using programs |
---|
73 | such as `uuencode'. If you do so it will slow down the processing of |
---|
74 | your bug. If you must submit multiple large files, use `shar', which |
---|
75 | allows us to read your message without having to run any decompression |
---|
76 | programs. |
---|
77 | |
---|
78 | To enable someone to investigate the bug, you should include all |
---|
79 | these things: |
---|
80 | |
---|
81 | * The version of GNU CC. You can get this by running it with the |
---|
82 | `-v' option. |
---|
83 | |
---|
84 | Without this, we won't know whether there is any point in looking |
---|
85 | for the bug in the current version of GNU CC. |
---|
86 | |
---|
87 | * A complete input file that will reproduce the bug. If the bug is |
---|
88 | in the C preprocessor, send a source file and any header files |
---|
89 | that it requires. If the bug is in the compiler proper (`cc1'), |
---|
90 | run your source file through the C preprocessor by doing `gcc -E |
---|
91 | SOURCEFILE > OUTFILE', then include the contents of OUTFILE in the |
---|
92 | bug report. (When you do this, use the same `-I', `-D' or `-U' |
---|
93 | options that you used in actual compilation.) |
---|
94 | |
---|
95 | A single statement is not enough of an example. In order to |
---|
96 | compile it, it must be embedded in a complete file of compiler |
---|
97 | input; and the bug might depend on the details of how this is done. |
---|
98 | |
---|
99 | Without a real example one can compile, all anyone can do about |
---|
100 | your bug report is wish you luck. It would be futile to try to |
---|
101 | guess how to provoke the bug. For example, bugs in register |
---|
102 | allocation and reloading frequently depend on every little detail |
---|
103 | of the function they happen in. |
---|
104 | |
---|
105 | Even if the input file that fails comes from a GNU program, you |
---|
106 | should still send the complete test case. Don't ask the GNU CC |
---|
107 | maintainers to do the extra work of obtaining the program in |
---|
108 | question--they are all overworked as it is. Also, the problem may |
---|
109 | depend on what is in the header files on your system; it is |
---|
110 | unreliable for the GNU CC maintainers to try the problem with the |
---|
111 | header files available to them. By sending CPP output, you can |
---|
112 | eliminate this source of uncertainty and save us a certain |
---|
113 | percentage of wild goose chases. |
---|
114 | |
---|
115 | * The command arguments you gave GNU CC or GNU C++ to compile that |
---|
116 | example and observe the bug. For example, did you use `-O'? To |
---|
117 | guarantee you won't omit something important, list all the options. |
---|
118 | |
---|
119 | If we were to try to guess the arguments, we would probably guess |
---|
120 | wrong and then we would not encounter the bug. |
---|
121 | |
---|
122 | * The type of machine you are using, and the operating system name |
---|
123 | and version number. |
---|
124 | |
---|
125 | * The operands you gave to the `configure' command when you installed |
---|
126 | the compiler. |
---|
127 | |
---|
128 | * A complete list of any modifications you have made to the compiler |
---|
129 | source. (We don't promise to investigate the bug unless it |
---|
130 | happens in an unmodified compiler. But if you've made |
---|
131 | modifications and don't tell us, then you are sending us on a wild |
---|
132 | goose chase.) |
---|
133 | |
---|
134 | Be precise about these changes. A description in English is not |
---|
135 | enough--send a context diff for them. |
---|
136 | |
---|
137 | Adding files of your own (such as a machine description for a |
---|
138 | machine we don't support) is a modification of the compiler source. |
---|
139 | |
---|
140 | * Details of any other deviations from the standard procedure for |
---|
141 | installing GNU CC. |
---|
142 | |
---|
143 | * A description of what behavior you observe that you believe is |
---|
144 | incorrect. For example, "The compiler gets a fatal signal," or, |
---|
145 | "The assembler instruction at line 208 in the output is incorrect." |
---|
146 | |
---|
147 | Of course, if the bug is that the compiler gets a fatal signal, |
---|
148 | then one can't miss it. But if the bug is incorrect output, the |
---|
149 | maintainer might not notice unless it is glaringly wrong. None of |
---|
150 | us has time to study all the assembler code from a 50-line C |
---|
151 | program just on the chance that one instruction might be wrong. |
---|
152 | We need *you* to do this part! |
---|
153 | |
---|
154 | Even if the problem you experience is a fatal signal, you should |
---|
155 | still say so explicitly. Suppose something strange is going on, |
---|
156 | such as, your copy of the compiler is out of synch, or you have |
---|
157 | encountered a bug in the C library on your system. (This has |
---|
158 | happened!) Your copy might crash and the copy here would not. If |
---|
159 | you said to expect a crash, then when the compiler here fails to |
---|
160 | crash, we would know that the bug was not happening. If you don't |
---|
161 | say to expect a crash, then we would not know whether the bug was |
---|
162 | happening. We would not be able to draw any conclusion from our |
---|
163 | observations. |
---|
164 | |
---|
165 | If the problem is a diagnostic when compiling GNU CC with some |
---|
166 | other compiler, say whether it is a warning or an error. |
---|
167 | |
---|
168 | Often the observed symptom is incorrect output when your program |
---|
169 | is run. Sad to say, this is not enough information unless the |
---|
170 | program is short and simple. None of us has time to study a large |
---|
171 | program to figure out how it would work if compiled correctly, |
---|
172 | much less which line of it was compiled wrong. So you will have |
---|
173 | to do that. Tell us which source line it is, and what incorrect |
---|
174 | result happens when that line is executed. A person who |
---|
175 | understands the program can find this as easily as finding a bug |
---|
176 | in the program itself. |
---|
177 | |
---|
178 | * If you send examples of assembler code output from GNU CC or GNU |
---|
179 | C++, please use `-g' when you make them. The debugging information |
---|
180 | includes source line numbers which are essential for correlating |
---|
181 | the output with the input. |
---|
182 | |
---|
183 | * If you wish to mention something in the GNU CC source, refer to it |
---|
184 | by context, not by line number. |
---|
185 | |
---|
186 | The line numbers in the development sources don't match those in |
---|
187 | your sources. Your line numbers would convey no useful |
---|
188 | information to the maintainers. |
---|
189 | |
---|
190 | * Additional information from a debugger might enable someone to |
---|
191 | find a problem on a machine which he does not have available. |
---|
192 | However, you need to think when you collect this information if |
---|
193 | you want it to have any chance of being useful. |
---|
194 | |
---|
195 | For example, many people send just a backtrace, but that is never |
---|
196 | useful by itself. A simple backtrace with arguments conveys little |
---|
197 | about GNU CC because the compiler is largely data-driven; the same |
---|
198 | functions are called over and over for different RTL insns, doing |
---|
199 | different things depending on the details of the insn. |
---|
200 | |
---|
201 | Most of the arguments listed in the backtrace are useless because |
---|
202 | they are pointers to RTL list structure. The numeric values of the |
---|
203 | pointers, which the debugger prints in the backtrace, have no |
---|
204 | significance whatever; all that matters is the contents of the |
---|
205 | objects they point to (and most of the contents are other such |
---|
206 | pointers). |
---|
207 | |
---|
208 | In addition, most compiler passes consist of one or more loops that |
---|
209 | scan the RTL insn sequence. The most vital piece of information |
---|
210 | about such a loop--which insn it has reached--is usually in a |
---|
211 | local variable, not in an argument. |
---|
212 | |
---|
213 | What you need to provide in addition to a backtrace are the values |
---|
214 | of the local variables for several stack frames up. When a local |
---|
215 | variable or an argument is an RTX, first print its value and then |
---|
216 | use the GDB command `pr' to print the RTL expression that it points |
---|
217 | to. (If GDB doesn't run on your machine, use your debugger to call |
---|
218 | the function `debug_rtx' with the RTX as an argument.) In |
---|
219 | general, whenever a variable is a pointer, its value is no use |
---|
220 | without the data it points to. |
---|
221 | |
---|
222 | Here are some things that are not necessary: |
---|
223 | |
---|
224 | * A description of the envelope of the bug. |
---|
225 | |
---|
226 | Often people who encounter a bug spend a lot of time investigating |
---|
227 | which changes to the input file will make the bug go away and which |
---|
228 | changes will not affect it. |
---|
229 | |
---|
230 | This is often time consuming and not very useful, because the way |
---|
231 | we will find the bug is by running a single example under the |
---|
232 | debugger with breakpoints, not by pure deduction from a series of |
---|
233 | examples. You might as well save your time for something else. |
---|
234 | |
---|
235 | Of course, if you can find a simpler example to report *instead* of |
---|
236 | the original one, that is a convenience. Errors in the output |
---|
237 | will be easier to spot, running under the debugger will take less |
---|
238 | time, etc. Most GNU CC bugs involve just one function, so the |
---|
239 | most straightforward way to simplify an example is to delete all |
---|
240 | the function definitions except the one where the bug occurs. |
---|
241 | Those earlier in the file may be replaced by external declarations |
---|
242 | if the crucial function depends on them. (Exception: inline |
---|
243 | functions may affect compilation of functions defined later in the |
---|
244 | file.) |
---|
245 | |
---|
246 | However, simplification is not vital; if you don't want to do this, |
---|
247 | report the bug anyway and send the entire test case you used. |
---|
248 | |
---|
249 | * In particular, some people insert conditionals `#ifdef BUG' around |
---|
250 | a statement which, if removed, makes the bug not happen. These |
---|
251 | are just clutter; we won't pay any attention to them anyway. |
---|
252 | Besides, you should send us cpp output, and that can't have |
---|
253 | conditionals. |
---|
254 | |
---|
255 | * A patch for the bug. |
---|
256 | |
---|
257 | A patch for the bug is useful if it is a good one. But don't omit |
---|
258 | the necessary information, such as the test case, on the |
---|
259 | assumption that a patch is all we need. We might see problems |
---|
260 | with your patch and decide to fix the problem another way, or we |
---|
261 | might not understand it at all. |
---|
262 | |
---|
263 | Sometimes with a program as complicated as GNU CC it is very hard |
---|
264 | to construct an example that will make the program follow a |
---|
265 | certain path through the code. If you don't send the example, we |
---|
266 | won't be able to construct one, so we won't be able to verify that |
---|
267 | the bug is fixed. |
---|
268 | |
---|
269 | And if we can't understand what bug you are trying to fix, or why |
---|
270 | your patch should be an improvement, we won't install it. A test |
---|
271 | case will help us to understand. |
---|
272 | |
---|
273 | *Note Sending Patches::, for guidelines on how to make it easy for |
---|
274 | us to understand and install your patches. |
---|
275 | |
---|
276 | * A guess about what the bug is or what it depends on. |
---|
277 | |
---|
278 | Such guesses are usually wrong. Even I can't guess right about |
---|
279 | such things without first using the debugger to find the facts. |
---|
280 | |
---|
281 | * A core dump file. |
---|
282 | |
---|
283 | We have no way of examining a core dump for your type of machine |
---|
284 | unless we have an identical system--and if we do have one, we |
---|
285 | should be able to reproduce the crash ourselves. |
---|
286 | |
---|
287 | |
---|
288 | File: gcc.info, Node: Sending Patches, Prev: Bug Reporting, Up: Bugs |
---|
289 | |
---|
290 | Sending Patches for GNU CC |
---|
291 | ========================== |
---|
292 | |
---|
293 | If you would like to write bug fixes or improvements for the GNU C |
---|
294 | compiler, that is very helpful. Send suggested fixes to the bug report |
---|
295 | mailing list, `bug-gcc@prep.ai.mit.edu'. |
---|
296 | |
---|
297 | Please follow these guidelines so we can study your patches |
---|
298 | efficiently. If you don't follow these guidelines, your information |
---|
299 | might still be useful, but using it will take extra work. Maintaining |
---|
300 | GNU C is a lot of work in the best of circumstances, and we can't keep |
---|
301 | up unless you do your best to help. |
---|
302 | |
---|
303 | * Send an explanation with your changes of what problem they fix or |
---|
304 | what improvement they bring about. For a bug fix, just include a |
---|
305 | copy of the bug report, and explain why the change fixes the bug. |
---|
306 | |
---|
307 | (Referring to a bug report is not as good as including it, because |
---|
308 | then we will have to look it up, and we have probably already |
---|
309 | deleted it if we've already fixed the bug.) |
---|
310 | |
---|
311 | * Always include a proper bug report for the problem you think you |
---|
312 | have fixed. We need to convince ourselves that the change is |
---|
313 | right before installing it. Even if it is right, we might have |
---|
314 | trouble judging it if we don't have a way to reproduce the problem. |
---|
315 | |
---|
316 | * Include all the comments that are appropriate to help people |
---|
317 | reading the source in the future understand why this change was |
---|
318 | needed. |
---|
319 | |
---|
320 | * Don't mix together changes made for different reasons. Send them |
---|
321 | *individually*. |
---|
322 | |
---|
323 | If you make two changes for separate reasons, then we might not |
---|
324 | want to install them both. We might want to install just one. If |
---|
325 | you send them all jumbled together in a single set of diffs, we |
---|
326 | have to do extra work to disentangle them--to figure out which |
---|
327 | parts of the change serve which purpose. If we don't have time |
---|
328 | for this, we might have to ignore your changes entirely. |
---|
329 | |
---|
330 | If you send each change as soon as you have written it, with its |
---|
331 | own explanation, then the two changes never get tangled up, and we |
---|
332 | can consider each one properly without any extra work to |
---|
333 | disentangle them. |
---|
334 | |
---|
335 | Ideally, each change you send should be impossible to subdivide |
---|
336 | into parts that we might want to consider separately, because each |
---|
337 | of its parts gets its motivation from the other parts. |
---|
338 | |
---|
339 | * Send each change as soon as that change is finished. Sometimes |
---|
340 | people think they are helping us by accumulating many changes to |
---|
341 | send them all together. As explained above, this is absolutely |
---|
342 | the worst thing you could do. |
---|
343 | |
---|
344 | Since you should send each change separately, you might as well |
---|
345 | send it right away. That gives us the option of installing it |
---|
346 | immediately if it is important. |
---|
347 | |
---|
348 | * Use `diff -c' to make your diffs. Diffs without context are hard |
---|
349 | for us to install reliably. More than that, they make it hard for |
---|
350 | us to study the diffs to decide whether we want to install them. |
---|
351 | Unidiff format is better than contextless diffs, but not as easy |
---|
352 | to read as `-c' format. |
---|
353 | |
---|
354 | If you have GNU diff, use `diff -cp', which shows the name of the |
---|
355 | function that each change occurs in. |
---|
356 | |
---|
357 | * Write the change log entries for your changes. We get lots of |
---|
358 | changes, and we don't have time to do all the change log writing |
---|
359 | ourselves. |
---|
360 | |
---|
361 | Read the `ChangeLog' file to see what sorts of information to put |
---|
362 | in, and to learn the style that we use. The purpose of the change |
---|
363 | log is to show people where to find what was changed. So you need |
---|
364 | to be specific about what functions you changed; in large |
---|
365 | functions, it's often helpful to indicate where within the |
---|
366 | function the change was. |
---|
367 | |
---|
368 | On the other hand, once you have shown people where to find the |
---|
369 | change, you need not explain its purpose. Thus, if you add a new |
---|
370 | function, all you need to say about it is that it is new. If you |
---|
371 | feel that the purpose needs explaining, it probably does--but the |
---|
372 | explanation will be much more useful if you put it in comments in |
---|
373 | the code. |
---|
374 | |
---|
375 | If you would like your name to appear in the header line for who |
---|
376 | made the change, send us the header line. |
---|
377 | |
---|
378 | * When you write the fix, keep in mind that we can't install a |
---|
379 | change that would break other systems. |
---|
380 | |
---|
381 | People often suggest fixing a problem by changing |
---|
382 | machine-independent files such as `toplev.c' to do something |
---|
383 | special that a particular system needs. Sometimes it is totally |
---|
384 | obvious that such changes would break GNU CC for almost all users. |
---|
385 | We can't possibly make a change like that. At best it might tell |
---|
386 | us how to write another patch that would solve the problem |
---|
387 | acceptably. |
---|
388 | |
---|
389 | Sometimes people send fixes that *might* be an improvement in |
---|
390 | general--but it is hard to be sure of this. It's hard to install |
---|
391 | such changes because we have to study them very carefully. Of |
---|
392 | course, a good explanation of the reasoning by which you concluded |
---|
393 | the change was correct can help convince us. |
---|
394 | |
---|
395 | The safest changes are changes to the configuration files for a |
---|
396 | particular machine. These are safe because they can't create new |
---|
397 | bugs on other machines. |
---|
398 | |
---|
399 | Please help us keep up with the workload by designing the patch in |
---|
400 | a form that is good to install. |
---|
401 | |
---|
402 | |
---|
403 | File: gcc.info, Node: Service, Next: Contributing, Prev: Bugs, Up: Top |
---|
404 | |
---|
405 | How To Get Help with GNU CC |
---|
406 | *************************** |
---|
407 | |
---|
408 | If you need help installing, using or changing GNU CC, there are two |
---|
409 | ways to find it: |
---|
410 | |
---|
411 | * Send a message to a suitable network mailing list. First try |
---|
412 | `bug-gcc@prep.ai.mit.edu', and if that brings no response, try |
---|
413 | `help-gcc@prep.ai.mit.edu'. |
---|
414 | |
---|
415 | * Look in the service directory for someone who might help you for a |
---|
416 | fee. The service directory is found in the file named `SERVICE' |
---|
417 | in the GNU CC distribution. |
---|
418 | |
---|
419 | |
---|
420 | File: gcc.info, Node: Contributing, Next: VMS, Prev: Service, Up: Top |
---|
421 | |
---|
422 | Contributing to GNU CC Development |
---|
423 | ********************************** |
---|
424 | |
---|
425 | If you would like to help pretest GNU CC releases to assure they work |
---|
426 | well, or if you would like to work on improving GNU CC, please contact |
---|
427 | the maintainers at `bug-gcc@gnu.ai.mit.edu'. A pretester should be |
---|
428 | willing to try to investigate bugs as well as report them. |
---|
429 | |
---|
430 | If you'd like to work on improvements, please ask for suggested |
---|
431 | projects or suggest your own ideas. If you have already written an |
---|
432 | improvement, please tell us about it. If you have not yet started |
---|
433 | work, it is useful to contact `bug-gcc@prep.ai.mit.edu' before you |
---|
434 | start; the maintainers may be able to suggest ways to make your |
---|
435 | extension fit in better with the rest of GNU CC and with other |
---|
436 | development plans. |
---|
437 | |
---|
438 | |
---|
439 | File: gcc.info, Node: VMS, Next: Portability, Prev: Contributing, Up: Top |
---|
440 | |
---|
441 | Using GNU CC on VMS |
---|
442 | ******************* |
---|
443 | |
---|
444 | Here is how to use GNU CC on VMS. |
---|
445 | |
---|
446 | * Menu: |
---|
447 | |
---|
448 | * Include Files and VMS:: Where the preprocessor looks for the include files. |
---|
449 | * Global Declarations:: How to do globaldef, globalref and globalvalue with |
---|
450 | GNU CC. |
---|
451 | * VMS Misc:: Misc information. |
---|
452 | |
---|
453 | |
---|
454 | File: gcc.info, Node: Include Files and VMS, Next: Global Declarations, Up: VMS |
---|
455 | |
---|
456 | Include Files and VMS |
---|
457 | ===================== |
---|
458 | |
---|
459 | Due to the differences between the filesystems of Unix and VMS, GNU |
---|
460 | CC attempts to translate file names in `#include' into names that VMS |
---|
461 | will understand. The basic strategy is to prepend a prefix to the |
---|
462 | specification of the include file, convert the whole filename to a VMS |
---|
463 | filename, and then try to open the file. GNU CC tries various prefixes |
---|
464 | one by one until one of them succeeds: |
---|
465 | |
---|
466 | 1. The first prefix is the `GNU_CC_INCLUDE:' logical name: this is |
---|
467 | where GNU C header files are traditionally stored. If you wish to |
---|
468 | store header files in non-standard locations, then you can assign |
---|
469 | the logical `GNU_CC_INCLUDE' to be a search list, where each |
---|
470 | element of the list is suitable for use with a rooted logical. |
---|
471 | |
---|
472 | 2. The next prefix tried is `SYS$SYSROOT:[SYSLIB.]'. This is where |
---|
473 | VAX-C header files are traditionally stored. |
---|
474 | |
---|
475 | 3. If the include file specification by itself is a valid VMS |
---|
476 | filename, the preprocessor then uses this name with no prefix in |
---|
477 | an attempt to open the include file. |
---|
478 | |
---|
479 | 4. If the file specification is not a valid VMS filename (i.e. does |
---|
480 | not contain a device or a directory specifier, and contains a `/' |
---|
481 | character), the preprocessor tries to convert it from Unix syntax |
---|
482 | to VMS syntax. |
---|
483 | |
---|
484 | Conversion works like this: the first directory name becomes a |
---|
485 | device, and the rest of the directories are converted into |
---|
486 | VMS-format directory names. For example, the name `X11/foobar.h' |
---|
487 | is translated to `X11:[000000]foobar.h' or `X11:foobar.h', |
---|
488 | whichever one can be opened. This strategy allows you to assign a |
---|
489 | logical name to point to the actual location of the header files. |
---|
490 | |
---|
491 | 5. If none of these strategies succeeds, the `#include' fails. |
---|
492 | |
---|
493 | Include directives of the form: |
---|
494 | |
---|
495 | #include foobar |
---|
496 | |
---|
497 | are a common source of incompatibility between VAX-C and GNU CC. VAX-C |
---|
498 | treats this much like a standard `#include <foobar.h>' directive. That |
---|
499 | is incompatible with the ANSI C behavior implemented by GNU CC: to |
---|
500 | expand the name `foobar' as a macro. Macro expansion should eventually |
---|
501 | yield one of the two standard formats for `#include': |
---|
502 | |
---|
503 | #include "FILE" |
---|
504 | #include <FILE> |
---|
505 | |
---|
506 | If you have this problem, the best solution is to modify the source |
---|
507 | to convert the `#include' directives to one of the two standard forms. |
---|
508 | That will work with either compiler. If you want a quick and dirty fix, |
---|
509 | define the file names as macros with the proper expansion, like this: |
---|
510 | |
---|
511 | #define stdio <stdio.h> |
---|
512 | |
---|
513 | This will work, as long as the name doesn't conflict with anything else |
---|
514 | in the program. |
---|
515 | |
---|
516 | Another source of incompatibility is that VAX-C assumes that: |
---|
517 | |
---|
518 | #include "foobar" |
---|
519 | |
---|
520 | is actually asking for the file `foobar.h'. GNU CC does not make this |
---|
521 | assumption, and instead takes what you ask for literally; it tries to |
---|
522 | read the file `foobar'. The best way to avoid this problem is to |
---|
523 | always specify the desired file extension in your include directives. |
---|
524 | |
---|
525 | GNU CC for VMS is distributed with a set of include files that is |
---|
526 | sufficient to compile most general purpose programs. Even though the |
---|
527 | GNU CC distribution does not contain header files to define constants |
---|
528 | and structures for some VMS system-specific functions, there is no |
---|
529 | reason why you cannot use GNU CC with any of these functions. You first |
---|
530 | may have to generate or create header files, either by using the public |
---|
531 | domain utility `UNSDL' (which can be found on a DECUS tape), or by |
---|
532 | extracting the relevant modules from one of the system macro libraries, |
---|
533 | and using an editor to construct a C header file. |
---|
534 | |
---|
535 | A `#include' file name cannot contain a DECNET node name. The |
---|
536 | preprocessor reports an I/O error if you attempt to use a node name, |
---|
537 | whether explicitly, or implicitly via a logical name. |
---|
538 | |
---|
539 | |
---|
540 | File: gcc.info, Node: Global Declarations, Next: VMS Misc, Prev: Include Files and VMS, Up: VMS |
---|
541 | |
---|
542 | Global Declarations and VMS |
---|
543 | =========================== |
---|
544 | |
---|
545 | GNU CC does not provide the `globalref', `globaldef' and |
---|
546 | `globalvalue' keywords of VAX-C. You can get the same effect with an |
---|
547 | obscure feature of GAS, the GNU assembler. (This requires GAS version |
---|
548 | 1.39 or later.) The following macros allow you to use this feature in |
---|
549 | a fairly natural way: |
---|
550 | |
---|
551 | #ifdef __GNUC__ |
---|
552 | #define GLOBALREF(TYPE,NAME) \ |
---|
553 | TYPE NAME \ |
---|
554 | asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) |
---|
555 | #define GLOBALDEF(TYPE,NAME,VALUE) \ |
---|
556 | TYPE NAME \ |
---|
557 | asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ |
---|
558 | = VALUE |
---|
559 | #define GLOBALVALUEREF(TYPE,NAME) \ |
---|
560 | const TYPE NAME[1] \ |
---|
561 | asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) |
---|
562 | #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ |
---|
563 | const TYPE NAME[1] \ |
---|
564 | asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ |
---|
565 | = {VALUE} |
---|
566 | #else |
---|
567 | #define GLOBALREF(TYPE,NAME) \ |
---|
568 | globalref TYPE NAME |
---|
569 | #define GLOBALDEF(TYPE,NAME,VALUE) \ |
---|
570 | globaldef TYPE NAME = VALUE |
---|
571 | #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ |
---|
572 | globalvalue TYPE NAME = VALUE |
---|
573 | #define GLOBALVALUEREF(TYPE,NAME) \ |
---|
574 | globalvalue TYPE NAME |
---|
575 | #endif |
---|
576 | |
---|
577 | (The `_$$PsectAttributes_GLOBALSYMBOL' prefix at the start of the name |
---|
578 | is removed by the assembler, after it has modified the attributes of |
---|
579 | the symbol). These macros are provided in the VMS binaries |
---|
580 | distribution in a header file `GNU_HACKS.H'. An example of the usage |
---|
581 | is: |
---|
582 | |
---|
583 | GLOBALREF (int, ijk); |
---|
584 | GLOBALDEF (int, jkl, 0); |
---|
585 | |
---|
586 | The macros `GLOBALREF' and `GLOBALDEF' cannot be used |
---|
587 | straightforwardly for arrays, since there is no way to insert the array |
---|
588 | dimension into the declaration at the right place. However, you can |
---|
589 | declare an array with these macros if you first define a typedef for the |
---|
590 | array type, like this: |
---|
591 | |
---|
592 | typedef int intvector[10]; |
---|
593 | GLOBALREF (intvector, foo); |
---|
594 | |
---|
595 | Array and structure initializers will also break the macros; you can |
---|
596 | define the initializer to be a macro of its own, or you can expand the |
---|
597 | `GLOBALDEF' macro by hand. You may find a case where you wish to use |
---|
598 | the `GLOBALDEF' macro with a large array, but you are not interested in |
---|
599 | explicitly initializing each element of the array. In such cases you |
---|
600 | can use an initializer like: `{0,}', which will initialize the entire |
---|
601 | array to `0'. |
---|
602 | |
---|
603 | A shortcoming of this implementation is that a variable declared with |
---|
604 | `GLOBALVALUEREF' or `GLOBALVALUEDEF' is always an array. For example, |
---|
605 | the declaration: |
---|
606 | |
---|
607 | GLOBALVALUEREF(int, ijk); |
---|
608 | |
---|
609 | declares the variable `ijk' as an array of type `int [1]'. This is |
---|
610 | done because a globalvalue is actually a constant; its "value" is what |
---|
611 | the linker would normally consider an address. That is not how an |
---|
612 | integer value works in C, but it is how an array works. So treating |
---|
613 | the symbol as an array name gives consistent results--with the |
---|
614 | exception that the value seems to have the wrong type. *Don't try to |
---|
615 | access an element of the array.* It doesn't have any elements. The |
---|
616 | array "address" may not be the address of actual storage. |
---|
617 | |
---|
618 | The fact that the symbol is an array may lead to warnings where the |
---|
619 | variable is used. Insert type casts to avoid the warnings. Here is an |
---|
620 | example; it takes advantage of the ANSI C feature allowing macros that |
---|
621 | expand to use the same name as the macro itself. |
---|
622 | |
---|
623 | GLOBALVALUEREF (int, ss$_normal); |
---|
624 | GLOBALVALUEDEF (int, xyzzy,123); |
---|
625 | #ifdef __GNUC__ |
---|
626 | #define ss$_normal ((int) ss$_normal) |
---|
627 | #define xyzzy ((int) xyzzy) |
---|
628 | #endif |
---|
629 | |
---|
630 | Don't use `globaldef' or `globalref' with a variable whose type is |
---|
631 | an enumeration type; this is not implemented. Instead, make the |
---|
632 | variable an integer, and use a `globalvaluedef' for each of the |
---|
633 | enumeration values. An example of this would be: |
---|
634 | |
---|
635 | #ifdef __GNUC__ |
---|
636 | GLOBALDEF (int, color, 0); |
---|
637 | GLOBALVALUEDEF (int, RED, 0); |
---|
638 | GLOBALVALUEDEF (int, BLUE, 1); |
---|
639 | GLOBALVALUEDEF (int, GREEN, 3); |
---|
640 | #else |
---|
641 | enum globaldef color {RED, BLUE, GREEN = 3}; |
---|
642 | #endif |
---|
643 | |
---|
644 | |
---|
645 | File: gcc.info, Node: VMS Misc, Prev: Global Declarations, Up: VMS |
---|
646 | |
---|
647 | Other VMS Issues |
---|
648 | ================ |
---|
649 | |
---|
650 | GNU CC automatically arranges for `main' to return 1 by default if |
---|
651 | you fail to specify an explicit return value. This will be interpreted |
---|
652 | by VMS as a status code indicating a normal successful completion. |
---|
653 | Version 1 of GNU CC did not provide this default. |
---|
654 | |
---|
655 | GNU CC on VMS works only with the GNU assembler, GAS. You need |
---|
656 | version 1.37 or later of GAS in order to produce value debugging |
---|
657 | information for the VMS debugger. Use the ordinary VMS linker with the |
---|
658 | object files produced by GAS. |
---|
659 | |
---|
660 | Under previous versions of GNU CC, the generated code would |
---|
661 | occasionally give strange results when linked to the sharable `VAXCRTL' |
---|
662 | library. Now this should work. |
---|
663 | |
---|
664 | A caveat for use of `const' global variables: the `const' modifier |
---|
665 | must be specified in every external declaration of the variable in all |
---|
666 | of the source files that use that variable. Otherwise the linker will |
---|
667 | issue warnings about conflicting attributes for the variable. Your |
---|
668 | program will still work despite the warnings, but the variable will be |
---|
669 | placed in writable storage. |
---|
670 | |
---|
671 | Although the VMS linker does distinguish between upper and lower case |
---|
672 | letters in global symbols, most VMS compilers convert all such symbols |
---|
673 | into upper case and most run-time library routines also have upper case |
---|
674 | names. To be able to reliably call such routines, GNU CC (by means of |
---|
675 | the assembler GAS) converts global symbols into upper case like other |
---|
676 | VMS compilers. However, since the usual practice in C is to distinguish |
---|
677 | case, GNU CC (via GAS) tries to preserve usual C behavior by augmenting |
---|
678 | each name that is not all lower case. This means truncating the name |
---|
679 | to at most 23 characters and then adding more characters at the end |
---|
680 | which encode the case pattern of those 23. Names which contain at |
---|
681 | least one dollar sign are an exception; they are converted directly into |
---|
682 | upper case without augmentation. |
---|
683 | |
---|
684 | Name augmentation yields bad results for programs that use |
---|
685 | precompiled libraries (such as Xlib) which were generated by another |
---|
686 | compiler. You can use the compiler option `/NOCASE_HACK' to inhibit |
---|
687 | augmentation; it makes external C functions and variables |
---|
688 | case-independent as is usual on VMS. Alternatively, you could write |
---|
689 | all references to the functions and variables in such libraries using |
---|
690 | lower case; this will work on VMS, but is not portable to other |
---|
691 | systems. The compiler option `/NAMES' also provides control over |
---|
692 | global name handling. |
---|
693 | |
---|
694 | Function and variable names are handled somewhat differently with GNU |
---|
695 | C++. The GNU C++ compiler performs "name mangling" on function names, |
---|
696 | which means that it adds information to the function name to describe |
---|
697 | the data types of the arguments that the function takes. One result of |
---|
698 | this is that the name of a function can become very long. Since the |
---|
699 | VMS linker only recognizes the first 31 characters in a name, special |
---|
700 | action is taken to ensure that each function and variable has a unique |
---|
701 | name that can be represented in 31 characters. |
---|
702 | |
---|
703 | If the name (plus a name augmentation, if required) is less than 32 |
---|
704 | characters in length, then no special action is performed. If the name |
---|
705 | is longer than 31 characters, the assembler (GAS) will generate a hash |
---|
706 | string based upon the function name, truncate the function name to 23 |
---|
707 | characters, and append the hash string to the truncated name. If the |
---|
708 | `/VERBOSE' compiler option is used, the assembler will print both the |
---|
709 | full and truncated names of each symbol that is truncated. |
---|
710 | |
---|
711 | The `/NOCASE_HACK' compiler option should not be used when you are |
---|
712 | compiling programs that use libg++. libg++ has several instances of |
---|
713 | objects (i.e. `Filebuf' and `filebuf') which become indistinguishable |
---|
714 | in a case-insensitive environment. This leads to cases where you need |
---|
715 | to inhibit augmentation selectively (if you were using libg++ and Xlib |
---|
716 | in the same program, for example). There is no special feature for |
---|
717 | doing this, but you can get the result by defining a macro for each |
---|
718 | mixed case symbol for which you wish to inhibit augmentation. The |
---|
719 | macro should expand into the lower case equivalent of itself. For |
---|
720 | example: |
---|
721 | |
---|
722 | #define StuDlyCapS studlycaps |
---|
723 | |
---|
724 | These macro definitions can be placed in a header file to minimize |
---|
725 | the number of changes to your source code. |
---|
726 | |
---|
727 | |
---|
728 | File: gcc.info, Node: Portability, Next: Interface, Prev: VMS, Up: Top |
---|
729 | |
---|
730 | GNU CC and Portability |
---|
731 | ********************** |
---|
732 | |
---|
733 | The main goal of GNU CC was to make a good, fast compiler for |
---|
734 | machines in the class that the GNU system aims to run on: 32-bit |
---|
735 | machines that address 8-bit bytes and have several general registers. |
---|
736 | Elegance, theoretical power and simplicity are only secondary. |
---|
737 | |
---|
738 | GNU CC gets most of the information about the target machine from a |
---|
739 | machine description which gives an algebraic formula for each of the |
---|
740 | machine's instructions. This is a very clean way to describe the |
---|
741 | target. But when the compiler needs information that is difficult to |
---|
742 | express in this fashion, I have not hesitated to define an ad-hoc |
---|
743 | parameter to the machine description. The purpose of portability is to |
---|
744 | reduce the total work needed on the compiler; it was not of interest |
---|
745 | for its own sake. |
---|
746 | |
---|
747 | GNU CC does not contain machine dependent code, but it does contain |
---|
748 | code that depends on machine parameters such as endianness (whether the |
---|
749 | most significant byte has the highest or lowest address of the bytes in |
---|
750 | a word) and the availability of autoincrement addressing. In the |
---|
751 | RTL-generation pass, it is often necessary to have multiple strategies |
---|
752 | for generating code for a particular kind of syntax tree, strategies |
---|
753 | that are usable for different combinations of parameters. Often I have |
---|
754 | not tried to address all possible cases, but only the common ones or |
---|
755 | only the ones that I have encountered. As a result, a new target may |
---|
756 | require additional strategies. You will know if this happens because |
---|
757 | the compiler will call `abort'. Fortunately, the new strategies can be |
---|
758 | added in a machine-independent fashion, and will affect only the target |
---|
759 | machines that need them. |
---|
760 | |
---|
761 | |
---|
762 | File: gcc.info, Node: Interface, Next: Passes, Prev: Portability, Up: Top |
---|
763 | |
---|
764 | Interfacing to GNU CC Output |
---|
765 | **************************** |
---|
766 | |
---|
767 | GNU CC is normally configured to use the same function calling |
---|
768 | convention normally in use on the target system. This is done with the |
---|
769 | machine-description macros described (*note Target Macros::.). |
---|
770 | |
---|
771 | However, returning of structure and union values is done differently |
---|
772 | on some target machines. As a result, functions compiled with PCC |
---|
773 | returning such types cannot be called from code compiled with GNU CC, |
---|
774 | and vice versa. This does not cause trouble often because few Unix |
---|
775 | library routines return structures or unions. |
---|
776 | |
---|
777 | GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes |
---|
778 | long in the same registers used for `int' or `double' return values. |
---|
779 | (GNU CC typically allocates variables of such types in registers also.) |
---|
780 | Structures and unions of other sizes are returned by storing them into |
---|
781 | an address passed by the caller (usually in a register). The |
---|
782 | machine-description macros `STRUCT_VALUE' and `STRUCT_INCOMING_VALUE' |
---|
783 | tell GNU CC where to pass this address. |
---|
784 | |
---|
785 | By contrast, PCC on most target machines returns structures and |
---|
786 | unions of any size by copying the data into an area of static storage, |
---|
787 | and then returning the address of that storage as if it were a pointer |
---|
788 | value. The caller must copy the data from that memory area to the |
---|
789 | place where the value is wanted. This is slower than the method used |
---|
790 | by GNU CC, and fails to be reentrant. |
---|
791 | |
---|
792 | On some target machines, such as RISC machines and the 80386, the |
---|
793 | standard system convention is to pass to the subroutine the address of |
---|
794 | where to return the value. On these machines, GNU CC has been |
---|
795 | configured to be compatible with the standard compiler, when this method |
---|
796 | is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes. |
---|
797 | |
---|
798 | GNU CC uses the system's standard convention for passing arguments. |
---|
799 | On some machines, the first few arguments are passed in registers; in |
---|
800 | others, all are passed on the stack. It would be possible to use |
---|
801 | registers for argument passing on any machine, and this would probably |
---|
802 | result in a significant speedup. But the result would be complete |
---|
803 | incompatibility with code that follows the standard convention. So this |
---|
804 | change is practical only if you are switching to GNU CC as the sole C |
---|
805 | compiler for the system. We may implement register argument passing on |
---|
806 | certain machines once we have a complete GNU system so that we can |
---|
807 | compile the libraries with GNU CC. |
---|
808 | |
---|
809 | On some machines (particularly the Sparc), certain types of arguments |
---|
810 | are passed "by invisible reference". This means that the value is |
---|
811 | stored in memory, and the address of the memory location is passed to |
---|
812 | the subroutine. |
---|
813 | |
---|
814 | If you use `longjmp', beware of automatic variables. ANSI C says |
---|
815 | that automatic variables that are not declared `volatile' have undefined |
---|
816 | values after a `longjmp'. And this is all GNU CC promises to do, |
---|
817 | because it is very difficult to restore register variables correctly, |
---|
818 | and one of GNU CC's features is that it can put variables in registers |
---|
819 | without your asking it to. |
---|
820 | |
---|
821 | If you want a variable to be unaltered by `longjmp', and you don't |
---|
822 | want to write `volatile' because old C compilers don't accept it, just |
---|
823 | take the address of the variable. If a variable's address is ever |
---|
824 | taken, even if just to compute it and ignore it, then the variable |
---|
825 | cannot go in a register: |
---|
826 | |
---|
827 | { |
---|
828 | int careful; |
---|
829 | &careful; |
---|
830 | ... |
---|
831 | } |
---|
832 | |
---|
833 | Code compiled with GNU CC may call certain library routines. Most of |
---|
834 | them handle arithmetic for which there are no instructions. This |
---|
835 | includes multiply and divide on some machines, and floating point |
---|
836 | operations on any machine for which floating point support is disabled |
---|
837 | with `-msoft-float'. Some standard parts of the C library, such as |
---|
838 | `bcopy' or `memcpy', are also called automatically. The usual function |
---|
839 | call interface is used for calling the library routines. |
---|
840 | |
---|
841 | These library routines should be defined in the library `libgcc.a', |
---|
842 | which GNU CC automatically searches whenever it links a program. On |
---|
843 | machines that have multiply and divide instructions, if hardware |
---|
844 | floating point is in use, normally `libgcc.a' is not needed, but it is |
---|
845 | searched just in case. |
---|
846 | |
---|
847 | Each arithmetic function is defined in `libgcc1.c' to use the |
---|
848 | corresponding C arithmetic operator. As long as the file is compiled |
---|
849 | with another C compiler, which supports all the C arithmetic operators, |
---|
850 | this file will work portably. However, `libgcc1.c' does not work if |
---|
851 | compiled with GNU CC, because each arithmetic function would compile |
---|
852 | into a call to itself! |
---|
853 | |
---|