[8833] | 1 | This is Info file gcc.info, produced by Makeinfo-1.55 from the input |
---|
| 2 | 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 Free Software |
---|
| 10 | 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: Temporaries, Prev: Static Definitions, Up: C++ Misunderstandings |
---|
| 34 | |
---|
| 35 | Temporaries May Vanish Before You Expect |
---|
| 36 | ---------------------------------------- |
---|
| 37 | |
---|
| 38 | It is dangerous to use pointers or references to *portions* of a |
---|
| 39 | temporary object. The compiler may very well delete the object before |
---|
| 40 | you expect it to, leaving a pointer to garbage. The most common place |
---|
| 41 | where this problem crops up is in classes like the libg++ `String' |
---|
| 42 | class, that define a conversion function to type `char *' or `const |
---|
| 43 | char *'. However, any class that returns a pointer to some internal |
---|
| 44 | structure is potentially subject to this problem. |
---|
| 45 | |
---|
| 46 | For example, a program may use a function `strfunc' that returns |
---|
| 47 | `String' objects, and another function `charfunc' that operates on |
---|
| 48 | pointers to `char': |
---|
| 49 | |
---|
| 50 | String strfunc (); |
---|
| 51 | void charfunc (const char *); |
---|
| 52 | |
---|
| 53 | In this situation, it may seem natural to write |
---|
| 54 | `charfunc (strfunc ());' based on the knowledge that class `String' has |
---|
| 55 | an explicit conversion to `char' pointers. However, what really |
---|
| 56 | happens is akin to `charfunc (strfunc ().convert ());', where the |
---|
| 57 | `convert' method is a function to do the same data conversion normally |
---|
| 58 | performed by a cast. Since the last use of the temporary `String' |
---|
| 59 | object is the call to the conversion function, the compiler may delete |
---|
| 60 | that object before actually calling `charfunc'. The compiler has no |
---|
| 61 | way of knowing that deleting the `String' object will invalidate the |
---|
| 62 | pointer. The pointer then points to garbage, so that by the time |
---|
| 63 | `charfunc' is called, it gets an invalid argument. |
---|
| 64 | |
---|
| 65 | Code like this may run successfully under some other compilers, |
---|
| 66 | especially those that delete temporaries relatively late. However, the |
---|
| 67 | GNU C++ behavior is also standard-conforming, so if your program depends |
---|
| 68 | on late destruction of temporaries it is not portable. |
---|
| 69 | |
---|
| 70 | If you think this is surprising, you should be aware that the ANSI |
---|
| 71 | C++ committee continues to debate the lifetime-of-temporaries problem. |
---|
| 72 | |
---|
| 73 | For now, at least, the safe way to write such code is to give the |
---|
| 74 | temporary a name, which forces it to remain until the end of the scope |
---|
| 75 | of the name. For example: |
---|
| 76 | |
---|
| 77 | String& tmp = strfunc (); |
---|
| 78 | charfunc (tmp); |
---|
| 79 | |
---|
| 80 | |
---|
| 81 | File: gcc.info, Node: Protoize Caveats, Next: Non-bugs, Prev: C++ Misunderstandings, Up: Trouble |
---|
| 82 | |
---|
| 83 | Caveats of using `protoize' |
---|
| 84 | =========================== |
---|
| 85 | |
---|
| 86 | The conversion programs `protoize' and `unprotoize' can sometimes |
---|
| 87 | change a source file in a way that won't work unless you rearrange it. |
---|
| 88 | |
---|
| 89 | * `protoize' can insert references to a type name or type tag before |
---|
| 90 | the definition, or in a file where they are not defined. |
---|
| 91 | |
---|
| 92 | If this happens, compiler error messages should show you where the |
---|
| 93 | new references are, so fixing the file by hand is straightforward. |
---|
| 94 | |
---|
| 95 | * There are some C constructs which `protoize' cannot figure out. |
---|
| 96 | For example, it can't determine argument types for declaring a |
---|
| 97 | pointer-to-function variable; this you must do by hand. `protoize' |
---|
| 98 | inserts a comment containing `???' each time it finds such a |
---|
| 99 | variable; so you can find all such variables by searching for this |
---|
| 100 | string. ANSI C does not require declaring the argument types of |
---|
| 101 | pointer-to-function types. |
---|
| 102 | |
---|
| 103 | * Using `unprotoize' can easily introduce bugs. If the program |
---|
| 104 | relied on prototypes to bring about conversion of arguments, these |
---|
| 105 | conversions will not take place in the program without prototypes. |
---|
| 106 | One case in which you can be sure `unprotoize' is safe is when you |
---|
| 107 | are removing prototypes that were made with `protoize'; if the |
---|
| 108 | program worked before without any prototypes, it will work again |
---|
| 109 | without them. |
---|
| 110 | |
---|
| 111 | You can find all the places where this problem might occur by |
---|
| 112 | compiling the program with the `-Wconversion' option. It prints a |
---|
| 113 | warning whenever an argument is converted. |
---|
| 114 | |
---|
| 115 | * Both conversion programs can be confused if there are macro calls |
---|
| 116 | in and around the text to be converted. In other words, the |
---|
| 117 | standard syntax for a declaration or definition must not result |
---|
| 118 | from expanding a macro. This problem is inherent in the design of |
---|
| 119 | C and cannot be fixed. If only a few functions have confusing |
---|
| 120 | macro calls, you can easily convert them manually. |
---|
| 121 | |
---|
| 122 | * `protoize' cannot get the argument types for a function whose |
---|
| 123 | definition was not actually compiled due to preprocessing |
---|
| 124 | conditionals. When this happens, `protoize' changes nothing in |
---|
| 125 | regard to such a function. `protoize' tries to detect such |
---|
| 126 | instances and warn about them. |
---|
| 127 | |
---|
| 128 | You can generally work around this problem by using `protoize' step |
---|
| 129 | by step, each time specifying a different set of `-D' options for |
---|
| 130 | compilation, until all of the functions have been converted. |
---|
| 131 | There is no automatic way to verify that you have got them all, |
---|
| 132 | however. |
---|
| 133 | |
---|
| 134 | * Confusion may result if there is an occasion to convert a function |
---|
| 135 | declaration or definition in a region of source code where there |
---|
| 136 | is more than one formal parameter list present. Thus, attempts to |
---|
| 137 | convert code containing multiple (conditionally compiled) versions |
---|
| 138 | of a single function header (in the same vicinity) may not produce |
---|
| 139 | the desired (or expected) results. |
---|
| 140 | |
---|
| 141 | If you plan on converting source files which contain such code, it |
---|
| 142 | is recommended that you first make sure that each conditionally |
---|
| 143 | compiled region of source code which contains an alternative |
---|
| 144 | function header also contains at least one additional follower |
---|
| 145 | token (past the final right parenthesis of the function header). |
---|
| 146 | This should circumvent the problem. |
---|
| 147 | |
---|
| 148 | * `unprotoize' can become confused when trying to convert a function |
---|
| 149 | definition or declaration which contains a declaration for a |
---|
| 150 | pointer-to-function formal argument which has the same name as the |
---|
| 151 | function being defined or declared. We recommand you avoid such |
---|
| 152 | choices of formal parameter names. |
---|
| 153 | |
---|
| 154 | * You might also want to correct some of the indentation by hand and |
---|
| 155 | break long lines. (The conversion programs don't write lines |
---|
| 156 | longer than eighty characters in any case.) |
---|
| 157 | |
---|
| 158 | |
---|
| 159 | File: gcc.info, Node: Non-bugs, Next: Warnings and Errors, Prev: Protoize Caveats, Up: Trouble |
---|
| 160 | |
---|
| 161 | Certain Changes We Don't Want to Make |
---|
| 162 | ===================================== |
---|
| 163 | |
---|
| 164 | This section lists changes that people frequently request, but which |
---|
| 165 | we do not make because we think GNU CC is better without them. |
---|
| 166 | |
---|
| 167 | * Checking the number and type of arguments to a function which has |
---|
| 168 | an old-fashioned definition and no prototype. |
---|
| 169 | |
---|
| 170 | Such a feature would work only occasionally--only for calls that |
---|
| 171 | appear in the same file as the called function, following the |
---|
| 172 | definition. The only way to check all calls reliably is to add a |
---|
| 173 | prototype for the function. But adding a prototype eliminates the |
---|
| 174 | motivation for this feature. So the feature is not worthwhile. |
---|
| 175 | |
---|
| 176 | * Warning about using an expression whose type is signed as a shift |
---|
| 177 | count. |
---|
| 178 | |
---|
| 179 | Shift count operands are probably signed more often than unsigned. |
---|
| 180 | Warning about this would cause far more annoyance than good. |
---|
| 181 | |
---|
| 182 | * Warning about assigning a signed value to an unsigned variable. |
---|
| 183 | |
---|
| 184 | Such assignments must be very common; warning about them would |
---|
| 185 | cause more annoyance than good. |
---|
| 186 | |
---|
| 187 | * Warning about unreachable code. |
---|
| 188 | |
---|
| 189 | It's very common to have unreachable code in machine-generated |
---|
| 190 | programs. For example, this happens normally in some files of GNU |
---|
| 191 | C itself. |
---|
| 192 | |
---|
| 193 | * Warning when a non-void function value is ignored. |
---|
| 194 | |
---|
| 195 | Coming as I do from a Lisp background, I balk at the idea that |
---|
| 196 | there is something dangerous about discarding a value. There are |
---|
| 197 | functions that return values which some callers may find useful; |
---|
| 198 | it makes no sense to clutter the program with a cast to `void' |
---|
| 199 | whenever the value isn't useful. |
---|
| 200 | |
---|
| 201 | * Assuming (for optimization) that the address of an external symbol |
---|
| 202 | is never zero. |
---|
| 203 | |
---|
| 204 | This assumption is false on certain systems when `#pragma weak' is |
---|
| 205 | used. |
---|
| 206 | |
---|
| 207 | * Making `-fshort-enums' the default. |
---|
| 208 | |
---|
| 209 | This would cause storage layout to be incompatible with most other |
---|
| 210 | C compilers. And it doesn't seem very important, given that you |
---|
| 211 | can get the same result in other ways. The case where it matters |
---|
| 212 | most is when the enumeration-valued object is inside a structure, |
---|
| 213 | and in that case you can specify a field width explicitly. |
---|
| 214 | |
---|
| 215 | * Making bitfields unsigned by default on particular machines where |
---|
| 216 | "the ABI standard" says to do so. |
---|
| 217 | |
---|
| 218 | The ANSI C standard leaves it up to the implementation whether a |
---|
| 219 | bitfield declared plain `int' is signed or not. This in effect |
---|
| 220 | creates two alternative dialects of C. |
---|
| 221 | |
---|
| 222 | The GNU C compiler supports both dialects; you can specify the |
---|
| 223 | signed dialect with `-fsigned-bitfields' and the unsigned dialect |
---|
| 224 | with `-funsigned-bitfields'. However, this leaves open the |
---|
| 225 | question of which dialect to use by default. |
---|
| 226 | |
---|
| 227 | Currently, the preferred dialect makes plain bitfields signed, |
---|
| 228 | because this is simplest. Since `int' is the same as `signed int' |
---|
| 229 | in every other context, it is cleanest for them to be the same in |
---|
| 230 | bitfields as well. |
---|
| 231 | |
---|
| 232 | Some computer manufacturers have published Application Binary |
---|
| 233 | Interface standards which specify that plain bitfields should be |
---|
| 234 | unsigned. It is a mistake, however, to say anything about this |
---|
| 235 | issue in an ABI. This is because the handling of plain bitfields |
---|
| 236 | distinguishes two dialects of C. Both dialects are meaningful on |
---|
| 237 | every type of machine. Whether a particular object file was |
---|
| 238 | compiled using signed bitfields or unsigned is of no concern to |
---|
| 239 | other object files, even if they access the same bitfields in the |
---|
| 240 | same data structures. |
---|
| 241 | |
---|
| 242 | A given program is written in one or the other of these two |
---|
| 243 | dialects. The program stands a chance to work on most any machine |
---|
| 244 | if it is compiled with the proper dialect. It is unlikely to work |
---|
| 245 | at all if compiled with the wrong dialect. |
---|
| 246 | |
---|
| 247 | Many users appreciate the GNU C compiler because it provides an |
---|
| 248 | environment that is uniform across machines. These users would be |
---|
| 249 | inconvenienced if the compiler treated plain bitfields differently |
---|
| 250 | on certain machines. |
---|
| 251 | |
---|
| 252 | Occasionally users write programs intended only for a particular |
---|
| 253 | machine type. On these occasions, the users would benefit if the |
---|
| 254 | GNU C compiler were to support by default the same dialect as the |
---|
| 255 | other compilers on that machine. But such applications are rare. |
---|
| 256 | And users writing a program to run on more than one type of |
---|
| 257 | machine cannot possibly benefit from this kind of compatibility. |
---|
| 258 | |
---|
| 259 | This is why GNU CC does and will treat plain bitfields in the same |
---|
| 260 | fashion on all types of machines (by default). |
---|
| 261 | |
---|
| 262 | There are some arguments for making bitfields unsigned by default |
---|
| 263 | on all machines. If, for example, this becomes a universal de |
---|
| 264 | facto standard, it would make sense for GNU CC to go along with |
---|
| 265 | it. This is something to be considered in the future. |
---|
| 266 | |
---|
| 267 | (Of course, users strongly concerned about portability should |
---|
| 268 | indicate explicitly in each bitfield whether it is signed or not. |
---|
| 269 | In this way, they write programs which have the same meaning in |
---|
| 270 | both C dialects.) |
---|
| 271 | |
---|
| 272 | * Undefining `__STDC__' when `-ansi' is not used. |
---|
| 273 | |
---|
| 274 | Currently, GNU CC defines `__STDC__' as long as you don't use |
---|
| 275 | `-traditional'. This provides good results in practice. |
---|
| 276 | |
---|
| 277 | Programmers normally use conditionals on `__STDC__' to ask whether |
---|
| 278 | it is safe to use certain features of ANSI C, such as function |
---|
| 279 | prototypes or ANSI token concatenation. Since plain `gcc' supports |
---|
| 280 | all the features of ANSI C, the correct answer to these questions |
---|
| 281 | is "yes". |
---|
| 282 | |
---|
| 283 | Some users try to use `__STDC__' to check for the availability of |
---|
| 284 | certain library facilities. This is actually incorrect usage in |
---|
| 285 | an ANSI C program, because the ANSI C standard says that a |
---|
| 286 | conforming freestanding implementation should define `__STDC__' |
---|
| 287 | even though it does not have the library facilities. `gcc -ansi |
---|
| 288 | -pedantic' is a conforming freestanding implementation, and it is |
---|
| 289 | therefore required to define `__STDC__', even though it does not |
---|
| 290 | come with an ANSI C library. |
---|
| 291 | |
---|
| 292 | Sometimes people say that defining `__STDC__' in a compiler that |
---|
| 293 | does not completely conform to the ANSI C standard somehow |
---|
| 294 | violates the standard. This is illogical. The standard is a |
---|
| 295 | standard for compilers that claim to support ANSI C, such as `gcc |
---|
| 296 | -ansi'--not for other compilers such as plain `gcc'. Whatever the |
---|
| 297 | ANSI C standard says is relevant to the design of plain `gcc' |
---|
| 298 | without `-ansi' only for pragmatic reasons, not as a requirement. |
---|
| 299 | |
---|
| 300 | * Undefining `__STDC__' in C++. |
---|
| 301 | |
---|
| 302 | Programs written to compile with C++-to-C translators get the |
---|
| 303 | value of `__STDC__' that goes with the C compiler that is |
---|
| 304 | subsequently used. These programs must test `__STDC__' to |
---|
| 305 | determine what kind of C preprocessor that compiler uses: whether |
---|
| 306 | they should concatenate tokens in the ANSI C fashion or in the |
---|
| 307 | traditional fashion. |
---|
| 308 | |
---|
| 309 | These programs work properly with GNU C++ if `__STDC__' is defined. |
---|
| 310 | They would not work otherwise. |
---|
| 311 | |
---|
| 312 | In addition, many header files are written to provide prototypes |
---|
| 313 | in ANSI C but not in traditional C. Many of these header files |
---|
| 314 | can work without change in C++ provided `__STDC__' is defined. If |
---|
| 315 | `__STDC__' is not defined, they will all fail, and will all need |
---|
| 316 | to be changed to test explicitly for C++ as well. |
---|
| 317 | |
---|
| 318 | * Deleting "empty" loops. |
---|
| 319 | |
---|
| 320 | GNU CC does not delete "empty" loops because the most likely reason |
---|
| 321 | you would put one in a program is to have a delay. Deleting them |
---|
| 322 | will not make real programs run any faster, so it would be |
---|
| 323 | pointless. |
---|
| 324 | |
---|
| 325 | It would be different if optimization of a nonempty loop could |
---|
| 326 | produce an empty one. But this generally can't happen. |
---|
| 327 | |
---|
| 328 | * Making side effects happen in the same order as in some other |
---|
| 329 | compiler. |
---|
| 330 | |
---|
| 331 | It is never safe to depend on the order of evaluation of side |
---|
| 332 | effects. For example, a function call like this may very well |
---|
| 333 | behave differently from one compiler to another: |
---|
| 334 | |
---|
| 335 | void func (int, int); |
---|
| 336 | |
---|
| 337 | int i = 2; |
---|
| 338 | func (i++, i++); |
---|
| 339 | |
---|
| 340 | There is no guarantee (in either the C or the C++ standard language |
---|
| 341 | definitions) that the increments will be evaluated in any |
---|
| 342 | particular order. Either increment might happen first. `func' |
---|
| 343 | might get the arguments `2, 3', or it might get `3, 2', or even |
---|
| 344 | `2, 2'. |
---|
| 345 | |
---|
| 346 | * Not allowing structures with volatile fields in registers. |
---|
| 347 | |
---|
| 348 | Strictly speaking, there is no prohibition in the ANSI C standard |
---|
| 349 | against allowing structures with volatile fields in registers, but |
---|
| 350 | it does not seem to make any sense and is probably not what you |
---|
| 351 | wanted to do. So the compiler will give an error message in this |
---|
| 352 | case. |
---|
| 353 | |
---|
| 354 | |
---|
| 355 | File: gcc.info, Node: Warnings and Errors, Prev: Non-bugs, Up: Trouble |
---|
| 356 | |
---|
| 357 | Warning Messages and Error Messages |
---|
| 358 | =================================== |
---|
| 359 | |
---|
| 360 | The GNU compiler can produce two kinds of diagnostics: errors and |
---|
| 361 | warnings. Each kind has a different purpose: |
---|
| 362 | |
---|
| 363 | *Errors* report problems that make it impossible to compile your |
---|
| 364 | program. GNU CC reports errors with the source file name and line |
---|
| 365 | number where the problem is apparent. |
---|
| 366 | |
---|
| 367 | *Warnings* report other unusual conditions in your code that *may* |
---|
| 368 | indicate a problem, although compilation can (and does) proceed. |
---|
| 369 | Warning messages also report the source file name and line number, |
---|
| 370 | but include the text `warning:' to distinguish them from error |
---|
| 371 | messages. |
---|
| 372 | |
---|
| 373 | Warnings may indicate danger points where you should check to make |
---|
| 374 | sure that your program really does what you intend; or the use of |
---|
| 375 | obsolete features; or the use of nonstandard features of GNU C or C++. |
---|
| 376 | Many warnings are issued only if you ask for them, with one of the `-W' |
---|
| 377 | options (for instance, `-Wall' requests a variety of useful warnings). |
---|
| 378 | |
---|
| 379 | GNU CC always tries to compile your program if possible; it never |
---|
| 380 | gratuitously rejects a program whose meaning is clear merely because |
---|
| 381 | (for instance) it fails to conform to a standard. In some cases, |
---|
| 382 | however, the C and C++ standards specify that certain extensions are |
---|
| 383 | forbidden, and a diagnostic *must* be issued by a conforming compiler. |
---|
| 384 | The `-pedantic' option tells GNU CC to issue warnings in such cases; |
---|
| 385 | `-pedantic-errors' says to make them errors instead. This does not |
---|
| 386 | mean that *all* non-ANSI constructs get warnings or errors. |
---|
| 387 | |
---|
| 388 | *Note Options to Request or Suppress Warnings: Warning Options, for |
---|
| 389 | more detail on these and related command-line options. |
---|
| 390 | |
---|
| 391 | |
---|
| 392 | File: gcc.info, Node: Bugs, Next: Service, Prev: Trouble, Up: Top |
---|
| 393 | |
---|
| 394 | Reporting Bugs |
---|
| 395 | ************** |
---|
| 396 | |
---|
| 397 | Your bug reports play an essential role in making GNU CC reliable. |
---|
| 398 | |
---|
| 399 | When you encounter a problem, the first thing to do is to see if it |
---|
| 400 | is already known. *Note Trouble::. If it isn't known, then you should |
---|
| 401 | report the problem. |
---|
| 402 | |
---|
| 403 | Reporting a bug may help you by bringing a solution to your problem, |
---|
| 404 | or it may not. (If it does not, look in the service directory; see |
---|
| 405 | *Note Service::.) In any case, the principal function of a bug report |
---|
| 406 | is to help the entire community by making the next version of GNU CC |
---|
| 407 | work better. Bug reports are your contribution to the maintenance of |
---|
| 408 | GNU CC. |
---|
| 409 | |
---|
| 410 | Since the maintainers are very overloaded, we cannot respond to every |
---|
| 411 | bug report. However, if the bug has not been fixed, we are likely to |
---|
| 412 | send you a patch and ask you to tell us whether it works. |
---|
| 413 | |
---|
| 414 | In order for a bug report to serve its purpose, you must include the |
---|
| 415 | information that makes for fixing the bug. |
---|
| 416 | |
---|
| 417 | * Menu: |
---|
| 418 | |
---|
| 419 | * Criteria: Bug Criteria. Have you really found a bug? |
---|
| 420 | * Where: Bug Lists. Where to send your bug report. |
---|
| 421 | * Reporting: Bug Reporting. How to report a bug effectively. |
---|
| 422 | * Patches: Sending Patches. How to send a patch for GNU CC. |
---|
| 423 | * Known: Trouble. Known problems. |
---|
| 424 | * Help: Service. Where to ask for help. |
---|
| 425 | |
---|
| 426 | |
---|
| 427 | File: gcc.info, Node: Bug Criteria, Next: Bug Lists, Up: Bugs |
---|
| 428 | |
---|
| 429 | Have You Found a Bug? |
---|
| 430 | ===================== |
---|
| 431 | |
---|
| 432 | If you are not sure whether you have found a bug, here are some |
---|
| 433 | guidelines: |
---|
| 434 | |
---|
| 435 | * If the compiler gets a fatal signal, for any input whatever, that |
---|
| 436 | is a compiler bug. Reliable compilers never crash. |
---|
| 437 | |
---|
| 438 | * If the compiler produces invalid assembly code, for any input |
---|
| 439 | whatever (except an `asm' statement), that is a compiler bug, |
---|
| 440 | unless the compiler reports errors (not just warnings) which would |
---|
| 441 | ordinarily prevent the assembler from being run. |
---|
| 442 | |
---|
| 443 | * If the compiler produces valid assembly code that does not |
---|
| 444 | correctly execute the input source code, that is a compiler bug. |
---|
| 445 | |
---|
| 446 | However, you must double-check to make sure, because you may have |
---|
| 447 | run into an incompatibility between GNU C and traditional C (*note |
---|
| 448 | Incompatibilities::.). These incompatibilities might be considered |
---|
| 449 | bugs, but they are inescapable consequences of valuable features. |
---|
| 450 | |
---|
| 451 | Or you may have a program whose behavior is undefined, which |
---|
| 452 | happened by chance to give the desired results with another C or |
---|
| 453 | C++ compiler. |
---|
| 454 | |
---|
| 455 | For example, in many nonoptimizing compilers, you can write `x;' |
---|
| 456 | at the end of a function instead of `return x;', with the same |
---|
| 457 | results. But the value of the function is undefined if `return' |
---|
| 458 | is omitted; it is not a bug when GNU CC produces different results. |
---|
| 459 | |
---|
| 460 | Problems often result from expressions with two increment |
---|
| 461 | operators, as in `f (*p++, *p++)'. Your previous compiler might |
---|
| 462 | have interpreted that expression the way you intended; GNU CC might |
---|
| 463 | interpret it another way. Neither compiler is wrong. The bug is |
---|
| 464 | in your code. |
---|
| 465 | |
---|
| 466 | After you have localized the error to a single source line, it |
---|
| 467 | should be easy to check for these things. If your program is |
---|
| 468 | correct and well defined, you have found a compiler bug. |
---|
| 469 | |
---|
| 470 | * If the compiler produces an error message for valid input, that is |
---|
| 471 | a compiler bug. |
---|
| 472 | |
---|
| 473 | * If the compiler does not produce an error message for invalid |
---|
| 474 | input, that is a compiler bug. However, you should note that your |
---|
| 475 | idea of "invalid input" might be my idea of "an extension" or |
---|
| 476 | "support for traditional practice". |
---|
| 477 | |
---|
| 478 | * If you are an experienced user of C or C++ compilers, your |
---|
| 479 | suggestions for improvement of GNU CC or GNU C++ are welcome in |
---|
| 480 | any case. |
---|
| 481 | |
---|
| 482 | |
---|
| 483 | File: gcc.info, Node: Bug Lists, Next: Bug Reporting, Prev: Bug Criteria, Up: Bugs |
---|
| 484 | |
---|
| 485 | Where to Report Bugs |
---|
| 486 | ==================== |
---|
| 487 | |
---|
| 488 | Send bug reports for GNU C to `bug-gcc@prep.ai.mit.edu'. |
---|
| 489 | |
---|
| 490 | Send bug reports for GNU C++ to `bug-g++@prep.ai.mit.edu'. If your |
---|
| 491 | bug involves the C++ class library libg++, send mail to |
---|
| 492 | `bug-lib-g++@prep.ai.mit.edu'. If you're not sure, you can send the |
---|
| 493 | bug report to both lists. |
---|
| 494 | |
---|
| 495 | *Do not send bug reports to `help-gcc@prep.ai.mit.edu' or to the |
---|
| 496 | newsgroup `gnu.gcc.help'.* Most users of GNU CC do not want to receive |
---|
| 497 | bug reports. Those that do, have asked to be on `bug-gcc' and/or |
---|
| 498 | `bug-g++'. |
---|
| 499 | |
---|
| 500 | The mailing lists `bug-gcc' and `bug-g++' both have newsgroups which |
---|
| 501 | serve as repeaters: `gnu.gcc.bug' and `gnu.g++.bug'. Each mailing list |
---|
| 502 | and its newsgroup carry exactly the same messages. |
---|
| 503 | |
---|
| 504 | Often people think of posting bug reports to the newsgroup instead of |
---|
| 505 | mailing them. This appears to work, but it has one problem which can be |
---|
| 506 | crucial: a newsgroup posting does not contain a mail path back to the |
---|
| 507 | sender. Thus, if maintainers need more information, they may be unable |
---|
| 508 | to reach you. For this reason, you should always send bug reports by |
---|
| 509 | mail to the proper mailing list. |
---|
| 510 | |
---|
| 511 | As a last resort, send bug reports on paper to: |
---|
| 512 | |
---|
| 513 | GNU Compiler Bugs |
---|
| 514 | Free Software Foundation |
---|
| 515 | 59 Temple Place - Suite 330 |
---|
| 516 | Boston, MA 02111-1307, USA |
---|
| 517 | |
---|
| 518 | |
---|
| 519 | File: gcc.info, Node: Bug Reporting, Next: Sending Patches, Prev: Bug Lists, Up: Bugs |
---|
| 520 | |
---|
| 521 | How to Report Bugs |
---|
| 522 | ================== |
---|
| 523 | |
---|
| 524 | The fundamental principle of reporting bugs usefully is this: |
---|
| 525 | *report all the facts*. If you are not sure whether to state a fact or |
---|
| 526 | leave it out, state it! |
---|
| 527 | |
---|
| 528 | Often people omit facts because they think they know what causes the |
---|
| 529 | problem and they conclude that some details don't matter. Thus, you |
---|
| 530 | might assume that the name of the variable you use in an example does |
---|
| 531 | not matter. Well, probably it doesn't, but one cannot be sure. |
---|
| 532 | Perhaps the bug is a stray memory reference which happens to fetch from |
---|
| 533 | the location where that name is stored in memory; perhaps, if the name |
---|
| 534 | were different, the contents of that location would fool the compiler |
---|
| 535 | into doing the right thing despite the bug. Play it safe and give a |
---|
| 536 | specific, complete example. That is the easiest thing for you to do, |
---|
| 537 | and the most helpful. |
---|
| 538 | |
---|
| 539 | Keep in mind that the purpose of a bug report is to enable someone to |
---|
| 540 | fix the bug if it is not known. It isn't very important what happens if |
---|
| 541 | the bug is already known. Therefore, always write your bug reports on |
---|
| 542 | the assumption that the bug is not known. |
---|
| 543 | |
---|
| 544 | Sometimes people give a few sketchy facts and ask, "Does this ring a |
---|
| 545 | bell?" This cannot help us fix a bug, so it is basically useless. We |
---|
| 546 | respond by asking for enough details to enable us to investigate. You |
---|
| 547 | might as well expedite matters by sending them to begin with. |
---|
| 548 | |
---|
| 549 | Try to make your bug report self-contained. If we have to ask you |
---|
| 550 | for more information, it is best if you include all the previous |
---|
| 551 | information in your response, as well as the information that was |
---|
| 552 | missing. |
---|
| 553 | |
---|
| 554 | Please report each bug in a separate message. This makes it easier |
---|
| 555 | for us to track which bugs have been fixed and to forward your bugs |
---|
| 556 | reports to the appropriate maintainer. |
---|
| 557 | |
---|
| 558 | Do not compress and encode any part of your bug report using programs |
---|
| 559 | such as `uuencode'. If you do so it will slow down the processing of |
---|
| 560 | your bug. If you must submit multiple large files, use `shar', which |
---|
| 561 | allows us to read your message without having to run any decompression |
---|
| 562 | programs. |
---|
| 563 | |
---|
| 564 | To enable someone to investigate the bug, you should include all |
---|
| 565 | these things: |
---|
| 566 | |
---|
| 567 | * The version of GNU CC. You can get this by running it with the |
---|
| 568 | `-v' option. |
---|
| 569 | |
---|
| 570 | Without this, we won't know whether there is any point in looking |
---|
| 571 | for the bug in the current version of GNU CC. |
---|
| 572 | |
---|
| 573 | * A complete input file that will reproduce the bug. If the bug is |
---|
| 574 | in the C preprocessor, send a source file and any header files |
---|
| 575 | that it requires. If the bug is in the compiler proper (`cc1'), |
---|
| 576 | run your source file through the C preprocessor by doing `gcc -E |
---|
| 577 | SOURCEFILE > OUTFILE', then include the contents of OUTFILE in the |
---|
| 578 | bug report. (When you do this, use the same `-I', `-D' or `-U' |
---|
| 579 | options that you used in actual compilation.) |
---|
| 580 | |
---|
| 581 | A single statement is not enough of an example. In order to |
---|
| 582 | compile it, it must be embedded in a complete file of compiler |
---|
| 583 | input; and the bug might depend on the details of how this is done. |
---|
| 584 | |
---|
| 585 | Without a real example one can compile, all anyone can do about |
---|
| 586 | your bug report is wish you luck. It would be futile to try to |
---|
| 587 | guess how to provoke the bug. For example, bugs in register |
---|
| 588 | allocation and reloading frequently depend on every little detail |
---|
| 589 | of the function they happen in. |
---|
| 590 | |
---|
| 591 | Even if the input file that fails comes from a GNU program, you |
---|
| 592 | should still send the complete test case. Don't ask the GNU CC |
---|
| 593 | maintainers to do the extra work of obtaining the program in |
---|
| 594 | question--they are all overworked as it is. Also, the problem may |
---|
| 595 | depend on what is in the header files on your system; it is |
---|
| 596 | unreliable for the GNU CC maintainers to try the problem with the |
---|
| 597 | header files available to them. By sending CPP output, you can |
---|
| 598 | eliminate this source of uncertainty and save us a certain |
---|
| 599 | percentage of wild goose chases. |
---|
| 600 | |
---|
| 601 | * The command arguments you gave GNU CC or GNU C++ to compile that |
---|
| 602 | example and observe the bug. For example, did you use `-O'? To |
---|
| 603 | guarantee you won't omit something important, list all the options. |
---|
| 604 | |
---|
| 605 | If we were to try to guess the arguments, we would probably guess |
---|
| 606 | wrong and then we would not encounter the bug. |
---|
| 607 | |
---|
| 608 | * The type of machine you are using, and the operating system name |
---|
| 609 | and version number. |
---|
| 610 | |
---|
| 611 | * The operands you gave to the `configure' command when you installed |
---|
| 612 | the compiler. |
---|
| 613 | |
---|
| 614 | * A complete list of any modifications you have made to the compiler |
---|
| 615 | source. (We don't promise to investigate the bug unless it |
---|
| 616 | happens in an unmodified compiler. But if you've made |
---|
| 617 | modifications and don't tell us, then you are sending us on a wild |
---|
| 618 | goose chase.) |
---|
| 619 | |
---|
| 620 | Be precise about these changes. A description in English is not |
---|
| 621 | enough--send a context diff for them. |
---|
| 622 | |
---|
| 623 | Adding files of your own (such as a machine description for a |
---|
| 624 | machine we don't support) is a modification of the compiler source. |
---|
| 625 | |
---|
| 626 | * Details of any other deviations from the standard procedure for |
---|
| 627 | installing GNU CC. |
---|
| 628 | |
---|
| 629 | * A description of what behavior you observe that you believe is |
---|
| 630 | incorrect. For example, "The compiler gets a fatal signal," or, |
---|
| 631 | "The assembler instruction at line 208 in the output is incorrect." |
---|
| 632 | |
---|
| 633 | Of course, if the bug is that the compiler gets a fatal signal, |
---|
| 634 | then one can't miss it. But if the bug is incorrect output, the |
---|
| 635 | maintainer might not notice unless it is glaringly wrong. None of |
---|
| 636 | us has time to study all the assembler code from a 50-line C |
---|
| 637 | program just on the chance that one instruction might be wrong. |
---|
| 638 | We need *you* to do this part! |
---|
| 639 | |
---|
| 640 | Even if the problem you experience is a fatal signal, you should |
---|
| 641 | still say so explicitly. Suppose something strange is going on, |
---|
| 642 | such as, your copy of the compiler is out of synch, or you have |
---|
| 643 | encountered a bug in the C library on your system. (This has |
---|
| 644 | happened!) Your copy might crash and the copy here would not. If |
---|
| 645 | you said to expect a crash, then when the compiler here fails to |
---|
| 646 | crash, we would know that the bug was not happening. If you don't |
---|
| 647 | say to expect a crash, then we would not know whether the bug was |
---|
| 648 | happening. We would not be able to draw any conclusion from our |
---|
| 649 | observations. |
---|
| 650 | |
---|
| 651 | If the problem is a diagnostic when compiling GNU CC with some |
---|
| 652 | other compiler, say whether it is a warning or an error. |
---|
| 653 | |
---|
| 654 | Often the observed symptom is incorrect output when your program |
---|
| 655 | is run. Sad to say, this is not enough information unless the |
---|
| 656 | program is short and simple. None of us has time to study a large |
---|
| 657 | program to figure out how it would work if compiled correctly, |
---|
| 658 | much less which line of it was compiled wrong. So you will have |
---|
| 659 | to do that. Tell us which source line it is, and what incorrect |
---|
| 660 | result happens when that line is executed. A person who |
---|
| 661 | understands the program can find this as easily as finding a bug |
---|
| 662 | in the program itself. |
---|
| 663 | |
---|
| 664 | * If you send examples of assembler code output from GNU CC or GNU |
---|
| 665 | C++, please use `-g' when you make them. The debugging information |
---|
| 666 | includes source line numbers which are essential for correlating |
---|
| 667 | the output with the input. |
---|
| 668 | |
---|
| 669 | * If you wish to mention something in the GNU CC source, refer to it |
---|
| 670 | by context, not by line number. |
---|
| 671 | |
---|
| 672 | The line numbers in the development sources don't match those in |
---|
| 673 | your sources. Your line numbers would convey no useful |
---|
| 674 | information to the maintainers. |
---|
| 675 | |
---|
| 676 | * Additional information from a debugger might enable someone to |
---|
| 677 | find a problem on a machine which he does not have available. |
---|
| 678 | However, you need to think when you collect this information if |
---|
| 679 | you want it to have any chance of being useful. |
---|
| 680 | |
---|
| 681 | For example, many people send just a backtrace, but that is never |
---|
| 682 | useful by itself. A simple backtrace with arguments conveys little |
---|
| 683 | about GNU CC because the compiler is largely data-driven; the same |
---|
| 684 | functions are called over and over for different RTL insns, doing |
---|
| 685 | different things depending on the details of the insn. |
---|
| 686 | |
---|
| 687 | Most of the arguments listed in the backtrace are useless because |
---|
| 688 | they are pointers to RTL list structure. The numeric values of the |
---|
| 689 | pointers, which the debugger prints in the backtrace, have no |
---|
| 690 | significance whatever; all that matters is the contents of the |
---|
| 691 | objects they point to (and most of the contents are other such |
---|
| 692 | pointers). |
---|
| 693 | |
---|
| 694 | In addition, most compiler passes consist of one or more loops that |
---|
| 695 | scan the RTL insn sequence. The most vital piece of information |
---|
| 696 | about such a loop--which insn it has reached--is usually in a |
---|
| 697 | local variable, not in an argument. |
---|
| 698 | |
---|
| 699 | What you need to provide in addition to a backtrace are the values |
---|
| 700 | of the local variables for several stack frames up. When a local |
---|
| 701 | variable or an argument is an RTX, first print its value and then |
---|
| 702 | use the GDB command `pr' to print the RTL expression that it points |
---|
| 703 | to. (If GDB doesn't run on your machine, use your debugger to call |
---|
| 704 | the function `debug_rtx' with the RTX as an argument.) In |
---|
| 705 | general, whenever a variable is a pointer, its value is no use |
---|
| 706 | without the data it points to. |
---|
| 707 | |
---|
| 708 | Here are some things that are not necessary: |
---|
| 709 | |
---|
| 710 | * A description of the envelope of the bug. |
---|
| 711 | |
---|
| 712 | Often people who encounter a bug spend a lot of time investigating |
---|
| 713 | which changes to the input file will make the bug go away and which |
---|
| 714 | changes will not affect it. |
---|
| 715 | |
---|
| 716 | This is often time consuming and not very useful, because the way |
---|
| 717 | we will find the bug is by running a single example under the |
---|
| 718 | debugger with breakpoints, not by pure deduction from a series of |
---|
| 719 | examples. You might as well save your time for something else. |
---|
| 720 | |
---|
| 721 | Of course, if you can find a simpler example to report *instead* of |
---|
| 722 | the original one, that is a convenience. Errors in the output |
---|
| 723 | will be easier to spot, running under the debugger will take less |
---|
| 724 | time, etc. Most GNU CC bugs involve just one function, so the |
---|
| 725 | most straightforward way to simplify an example is to delete all |
---|
| 726 | the function definitions except the one where the bug occurs. |
---|
| 727 | Those earlier in the file may be replaced by external declarations |
---|
| 728 | if the crucial function depends on them. (Exception: inline |
---|
| 729 | functions may affect compilation of functions defined later in the |
---|
| 730 | file.) |
---|
| 731 | |
---|
| 732 | However, simplification is not vital; if you don't want to do this, |
---|
| 733 | report the bug anyway and send the entire test case you used. |
---|
| 734 | |
---|
| 735 | * In particular, some people insert conditionals `#ifdef BUG' around |
---|
| 736 | a statement which, if removed, makes the bug not happen. These |
---|
| 737 | are just clutter; we won't pay any attention to them anyway. |
---|
| 738 | Besides, you should send us cpp output, and that can't have |
---|
| 739 | conditionals. |
---|
| 740 | |
---|
| 741 | * A patch for the bug. |
---|
| 742 | |
---|
| 743 | A patch for the bug is useful if it is a good one. But don't omit |
---|
| 744 | the necessary information, such as the test case, on the |
---|
| 745 | assumption that a patch is all we need. We might see problems |
---|
| 746 | with your patch and decide to fix the problem another way, or we |
---|
| 747 | might not understand it at all. |
---|
| 748 | |
---|
| 749 | Sometimes with a program as complicated as GNU CC it is very hard |
---|
| 750 | to construct an example that will make the program follow a |
---|
| 751 | certain path through the code. If you don't send the example, we |
---|
| 752 | won't be able to construct one, so we won't be able to verify that |
---|
| 753 | the bug is fixed. |
---|
| 754 | |
---|
| 755 | And if we can't understand what bug you are trying to fix, or why |
---|
| 756 | your patch should be an improvement, we won't install it. A test |
---|
| 757 | case will help us to understand. |
---|
| 758 | |
---|
| 759 | *Note Sending Patches::, for guidelines on how to make it easy for |
---|
| 760 | us to understand and install your patches. |
---|
| 761 | |
---|
| 762 | * A guess about what the bug is or what it depends on. |
---|
| 763 | |
---|
| 764 | Such guesses are usually wrong. Even I can't guess right about |
---|
| 765 | such things without first using the debugger to find the facts. |
---|
| 766 | |
---|
| 767 | * A core dump file. |
---|
| 768 | |
---|
| 769 | We have no way of examining a core dump for your type of machine |
---|
| 770 | unless we have an identical system--and if we do have one, we |
---|
| 771 | should be able to reproduce the crash ourselves. |
---|
| 772 | |
---|
| 773 | |
---|
| 774 | File: gcc.info, Node: Sending Patches, Prev: Bug Reporting, Up: Bugs |
---|
| 775 | |
---|
| 776 | Sending Patches for GNU CC |
---|
| 777 | ========================== |
---|
| 778 | |
---|
| 779 | If you would like to write bug fixes or improvements for the GNU C |
---|
| 780 | compiler, that is very helpful. Send suggested fixes to the bug report |
---|
| 781 | mailing list, `bug-gcc@prep.ai.mit.edu'. |
---|
| 782 | |
---|
| 783 | Please follow these guidelines so we can study your patches |
---|
| 784 | efficiently. If you don't follow these guidelines, your information |
---|
| 785 | might still be useful, but using it will take extra work. Maintaining |
---|
| 786 | GNU C is a lot of work in the best of circumstances, and we can't keep |
---|
| 787 | up unless you do your best to help. |
---|
| 788 | |
---|
| 789 | * Send an explanation with your changes of what problem they fix or |
---|
| 790 | what improvement they bring about. For a bug fix, just include a |
---|
| 791 | copy of the bug report, and explain why the change fixes the bug. |
---|
| 792 | |
---|
| 793 | (Referring to a bug report is not as good as including it, because |
---|
| 794 | then we will have to look it up, and we have probably already |
---|
| 795 | deleted it if we've already fixed the bug.) |
---|
| 796 | |
---|
| 797 | * Always include a proper bug report for the problem you think you |
---|
| 798 | have fixed. We need to convince ourselves that the change is |
---|
| 799 | right before installing it. Even if it is right, we might have |
---|
| 800 | trouble judging it if we don't have a way to reproduce the problem. |
---|
| 801 | |
---|
| 802 | * Include all the comments that are appropriate to help people |
---|
| 803 | reading the source in the future understand why this change was |
---|
| 804 | needed. |
---|
| 805 | |
---|
| 806 | * Don't mix together changes made for different reasons. Send them |
---|
| 807 | *individually*. |
---|
| 808 | |
---|
| 809 | If you make two changes for separate reasons, then we might not |
---|
| 810 | want to install them both. We might want to install just one. If |
---|
| 811 | you send them all jumbled together in a single set of diffs, we |
---|
| 812 | have to do extra work to disentangle them--to figure out which |
---|
| 813 | parts of the change serve which purpose. If we don't have time |
---|
| 814 | for this, we might have to ignore your changes entirely. |
---|
| 815 | |
---|
| 816 | If you send each change as soon as you have written it, with its |
---|
| 817 | own explanation, then the two changes never get tangled up, and we |
---|
| 818 | can consider each one properly without any extra work to |
---|
| 819 | disentangle them. |
---|
| 820 | |
---|
| 821 | Ideally, each change you send should be impossible to subdivide |
---|
| 822 | into parts that we might want to consider separately, because each |
---|
| 823 | of its parts gets its motivation from the other parts. |
---|
| 824 | |
---|
| 825 | * Send each change as soon as that change is finished. Sometimes |
---|
| 826 | people think they are helping us by accumulating many changes to |
---|
| 827 | send them all together. As explained above, this is absolutely |
---|
| 828 | the worst thing you could do. |
---|
| 829 | |
---|
| 830 | Since you should send each change separately, you might as well |
---|
| 831 | send it right away. That gives us the option of installing it |
---|
| 832 | immediately if it is important. |
---|
| 833 | |
---|
| 834 | * Use `diff -c' to make your diffs. Diffs without context are hard |
---|
| 835 | for us to install reliably. More than that, they make it hard for |
---|
| 836 | us to study the diffs to decide whether we want to install them. |
---|
| 837 | Unidiff format is better than contextless diffs, but not as easy |
---|
| 838 | to read as `-c' format. |
---|
| 839 | |
---|
| 840 | If you have GNU diff, use `diff -cp', which shows the name of the |
---|
| 841 | function that each change occurs in. |
---|
| 842 | |
---|
| 843 | * Write the change log entries for your changes. We get lots of |
---|
| 844 | changes, and we don't have time to do all the change log writing |
---|
| 845 | ourselves. |
---|
| 846 | |
---|
| 847 | Read the `ChangeLog' file to see what sorts of information to put |
---|
| 848 | in, and to learn the style that we use. The purpose of the change |
---|
| 849 | log is to show people where to find what was changed. So you need |
---|
| 850 | to be specific about what functions you changed; in large |
---|
| 851 | functions, it's often helpful to indicate where within the |
---|
| 852 | function the change was. |
---|
| 853 | |
---|
| 854 | On the other hand, once you have shown people where to find the |
---|
| 855 | change, you need not explain its purpose. Thus, if you add a new |
---|
| 856 | function, all you need to say about it is that it is new. If you |
---|
| 857 | feel that the purpose needs explaining, it probably does--but the |
---|
| 858 | explanation will be much more useful if you put it in comments in |
---|
| 859 | the code. |
---|
| 860 | |
---|
| 861 | If you would like your name to appear in the header line for who |
---|
| 862 | made the change, send us the header line. |
---|
| 863 | |
---|
| 864 | * When you write the fix, keep in mind that we can't install a |
---|
| 865 | change that would break other systems. |
---|
| 866 | |
---|
| 867 | People often suggest fixing a problem by changing |
---|
| 868 | machine-independent files such as `toplev.c' to do something |
---|
| 869 | special that a particular system needs. Sometimes it is totally |
---|
| 870 | obvious that such changes would break GNU CC for almost all users. |
---|
| 871 | We can't possibly make a change like that. At best it might tell |
---|
| 872 | us how to write another patch that would solve the problem |
---|
| 873 | acceptably. |
---|
| 874 | |
---|
| 875 | Sometimes people send fixes that *might* be an improvement in |
---|
| 876 | general--but it is hard to be sure of this. It's hard to install |
---|
| 877 | such changes because we have to study them very carefully. Of |
---|
| 878 | course, a good explanation of the reasoning by which you concluded |
---|
| 879 | the change was correct can help convince us. |
---|
| 880 | |
---|
| 881 | The safest changes are changes to the configuration files for a |
---|
| 882 | particular machine. These are safe because they can't create new |
---|
| 883 | bugs on other machines. |
---|
| 884 | |
---|
| 885 | Please help us keep up with the workload by designing the patch in |
---|
| 886 | a form that is good to install. |
---|
| 887 | |
---|
| 888 | |
---|
| 889 | File: gcc.info, Node: Service, Next: VMS, Prev: Bugs, Up: Top |
---|
| 890 | |
---|
| 891 | How To Get Help with GNU CC |
---|
| 892 | *************************** |
---|
| 893 | |
---|
| 894 | If you need help installing, using or changing GNU CC, there are two |
---|
| 895 | ways to find it: |
---|
| 896 | |
---|
| 897 | * Send a message to a suitable network mailing list. First try |
---|
| 898 | `bug-gcc@prep.ai.mit.edu', and if that brings no response, try |
---|
| 899 | `help-gcc@prep.ai.mit.edu'. |
---|
| 900 | |
---|
| 901 | * Look in the service directory for someone who might help you for a |
---|
| 902 | fee. The service directory is found in the file named `SERVICE' |
---|
| 903 | in the GNU CC distribution. |
---|
| 904 | |
---|
| 905 | |
---|
| 906 | File: gcc.info, Node: VMS, Next: Portability, Prev: Service, Up: Top |
---|
| 907 | |
---|
| 908 | Using GNU CC on VMS |
---|
| 909 | ******************* |
---|
| 910 | |
---|
| 911 | Here is how to use GNU CC on VMS. |
---|
| 912 | |
---|
| 913 | * Menu: |
---|
| 914 | |
---|
| 915 | * Include Files and VMS:: Where the preprocessor looks for the include files. |
---|
| 916 | * Global Declarations:: How to do globaldef, globalref and globalvalue with |
---|
| 917 | GNU CC. |
---|
| 918 | * VMS Misc:: Misc information. |
---|
| 919 | |
---|
| 920 | |
---|
| 921 | File: gcc.info, Node: Include Files and VMS, Next: Global Declarations, Up: VMS |
---|
| 922 | |
---|
| 923 | Include Files and VMS |
---|
| 924 | ===================== |
---|
| 925 | |
---|
| 926 | Due to the differences between the filesystems of Unix and VMS, GNU |
---|
| 927 | CC attempts to translate file names in `#include' into names that VMS |
---|
| 928 | will understand. The basic strategy is to prepend a prefix to the |
---|
| 929 | specification of the include file, convert the whole filename to a VMS |
---|
| 930 | filename, and then try to open the file. GNU CC tries various prefixes |
---|
| 931 | one by one until one of them succeeds: |
---|
| 932 | |
---|
| 933 | 1. The first prefix is the `GNU_CC_INCLUDE:' logical name: this is |
---|
| 934 | where GNU C header files are traditionally stored. If you wish to |
---|
| 935 | store header files in non-standard locations, then you can assign |
---|
| 936 | the logical `GNU_CC_INCLUDE' to be a search list, where each |
---|
| 937 | element of the list is suitable for use with a rooted logical. |
---|
| 938 | |
---|
| 939 | 2. The next prefix tried is `SYS$SYSROOT:[SYSLIB.]'. This is where |
---|
| 940 | VAX-C header files are traditionally stored. |
---|
| 941 | |
---|
| 942 | 3. If the include file specification by itself is a valid VMS |
---|
| 943 | filename, the preprocessor then uses this name with no prefix in |
---|
| 944 | an attempt to open the include file. |
---|
| 945 | |
---|
| 946 | 4. If the file specification is not a valid VMS filename (i.e. does |
---|
| 947 | not contain a device or a directory specifier, and contains a `/' |
---|
| 948 | character), the preprocessor tries to convert it from Unix syntax |
---|
| 949 | to VMS syntax. |
---|
| 950 | |
---|
| 951 | Conversion works like this: the first directory name becomes a |
---|
| 952 | device, and the rest of the directories are converted into |
---|
| 953 | VMS-format directory names. For example, the name `X11/foobar.h' |
---|
| 954 | is translated to `X11:[000000]foobar.h' or `X11:foobar.h', |
---|
| 955 | whichever one can be opened. This strategy allows you to assign a |
---|
| 956 | logical name to point to the actual location of the header files. |
---|
| 957 | |
---|
| 958 | 5. If none of these strategies succeeds, the `#include' fails. |
---|
| 959 | |
---|
| 960 | Include directives of the form: |
---|
| 961 | |
---|
| 962 | #include foobar |
---|
| 963 | |
---|
| 964 | are a common source of incompatibility between VAX-C and GNU CC. VAX-C |
---|
| 965 | treats this much like a standard `#include <foobar.h>' directive. That |
---|
| 966 | is incompatible with the ANSI C behavior implemented by GNU CC: to |
---|
| 967 | expand the name `foobar' as a macro. Macro expansion should eventually |
---|
| 968 | yield one of the two standard formats for `#include': |
---|
| 969 | |
---|
| 970 | #include "FILE" |
---|
| 971 | #include <FILE> |
---|
| 972 | |
---|
| 973 | If you have this problem, the best solution is to modify the source |
---|
| 974 | to convert the `#include' directives to one of the two standard forms. |
---|
| 975 | That will work with either compiler. If you want a quick and dirty fix, |
---|
| 976 | define the file names as macros with the proper expansion, like this: |
---|
| 977 | |
---|
| 978 | #define stdio <stdio.h> |
---|
| 979 | |
---|
| 980 | This will work, as long as the name doesn't conflict with anything else |
---|
| 981 | in the program. |
---|
| 982 | |
---|
| 983 | Another source of incompatibility is that VAX-C assumes that: |
---|
| 984 | |
---|
| 985 | #include "foobar" |
---|
| 986 | |
---|
| 987 | is actually asking for the file `foobar.h'. GNU CC does not make this |
---|
| 988 | assumption, and instead takes what you ask for literally; it tries to |
---|
| 989 | read the file `foobar'. The best way to avoid this problem is to |
---|
| 990 | always specify the desired file extension in your include directives. |
---|
| 991 | |
---|
| 992 | GNU CC for VMS is distributed with a set of include files that is |
---|
| 993 | sufficient to compile most general purpose programs. Even though the |
---|
| 994 | GNU CC distribution does not contain header files to define constants |
---|
| 995 | and structures for some VMS system-specific functions, there is no |
---|
| 996 | reason why you cannot use GNU CC with any of these functions. You first |
---|
| 997 | may have to generate or create header files, either by using the public |
---|
| 998 | domain utility `UNSDL' (which can be found on a DECUS tape), or by |
---|
| 999 | extracting the relevant modules from one of the system macro libraries, |
---|
| 1000 | and using an editor to construct a C header file. |
---|
| 1001 | |
---|
| 1002 | A `#include' file name cannot contain a DECNET node name. The |
---|
| 1003 | preprocessor reports an I/O error if you attempt to use a node name, |
---|
| 1004 | whether explicitly, or implicitly via a logical name. |
---|
| 1005 | |
---|
| 1006 | |
---|
| 1007 | File: gcc.info, Node: Global Declarations, Next: VMS Misc, Prev: Include Files and VMS, Up: VMS |
---|
| 1008 | |
---|
| 1009 | Global Declarations and VMS |
---|
| 1010 | =========================== |
---|
| 1011 | |
---|
| 1012 | GNU CC does not provide the `globalref', `globaldef' and |
---|
| 1013 | `globalvalue' keywords of VAX-C. You can get the same effect with an |
---|
| 1014 | obscure feature of GAS, the GNU assembler. (This requires GAS version |
---|
| 1015 | 1.39 or later.) The following macros allow you to use this feature in |
---|
| 1016 | a fairly natural way: |
---|
| 1017 | |
---|
| 1018 | #ifdef __GNUC__ |
---|
| 1019 | #define GLOBALREF(TYPE,NAME) \ |
---|
| 1020 | TYPE NAME \ |
---|
| 1021 | asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) |
---|
| 1022 | #define GLOBALDEF(TYPE,NAME,VALUE) \ |
---|
| 1023 | TYPE NAME \ |
---|
| 1024 | asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ |
---|
| 1025 | = VALUE |
---|
| 1026 | #define GLOBALVALUEREF(TYPE,NAME) \ |
---|
| 1027 | const TYPE NAME[1] \ |
---|
| 1028 | asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) |
---|
| 1029 | #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ |
---|
| 1030 | const TYPE NAME[1] \ |
---|
| 1031 | asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ |
---|
| 1032 | = {VALUE} |
---|
| 1033 | #else |
---|
| 1034 | #define GLOBALREF(TYPE,NAME) \ |
---|
| 1035 | globalref TYPE NAME |
---|
| 1036 | #define GLOBALDEF(TYPE,NAME,VALUE) \ |
---|
| 1037 | globaldef TYPE NAME = VALUE |
---|
| 1038 | #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ |
---|
| 1039 | globalvalue TYPE NAME = VALUE |
---|
| 1040 | #define GLOBALVALUEREF(TYPE,NAME) \ |
---|
| 1041 | globalvalue TYPE NAME |
---|
| 1042 | #endif |
---|
| 1043 | |
---|
| 1044 | (The `_$$PsectAttributes_GLOBALSYMBOL' prefix at the start of the name |
---|
| 1045 | is removed by the assembler, after it has modified the attributes of |
---|
| 1046 | the symbol). These macros are provided in the VMS binaries |
---|
| 1047 | distribution in a header file `GNU_HACKS.H'. An example of the usage |
---|
| 1048 | is: |
---|
| 1049 | |
---|
| 1050 | GLOBALREF (int, ijk); |
---|
| 1051 | GLOBALDEF (int, jkl, 0); |
---|
| 1052 | |
---|
| 1053 | The macros `GLOBALREF' and `GLOBALDEF' cannot be used |
---|
| 1054 | straightforwardly for arrays, since there is no way to insert the array |
---|
| 1055 | dimension into the declaration at the right place. However, you can |
---|
| 1056 | declare an array with these macros if you first define a typedef for the |
---|
| 1057 | array type, like this: |
---|
| 1058 | |
---|
| 1059 | typedef int intvector[10]; |
---|
| 1060 | GLOBALREF (intvector, foo); |
---|
| 1061 | |
---|
| 1062 | Array and structure initializers will also break the macros; you can |
---|
| 1063 | define the initializer to be a macro of its own, or you can expand the |
---|
| 1064 | `GLOBALDEF' macro by hand. You may find a case where you wish to use |
---|
| 1065 | the `GLOBALDEF' macro with a large array, but you are not interested in |
---|
| 1066 | explicitly initializing each element of the array. In such cases you |
---|
| 1067 | can use an initializer like: `{0,}', which will initialize the entire |
---|
| 1068 | array to `0'. |
---|
| 1069 | |
---|
| 1070 | A shortcoming of this implementation is that a variable declared with |
---|
| 1071 | `GLOBALVALUEREF' or `GLOBALVALUEDEF' is always an array. For example, |
---|
| 1072 | the declaration: |
---|
| 1073 | |
---|
| 1074 | GLOBALVALUEREF(int, ijk); |
---|
| 1075 | |
---|
| 1076 | declares the variable `ijk' as an array of type `int [1]'. This is |
---|
| 1077 | done because a globalvalue is actually a constant; its "value" is what |
---|
| 1078 | the linker would normally consider an address. That is not how an |
---|
| 1079 | integer value works in C, but it is how an array works. So treating |
---|
| 1080 | the symbol as an array name gives consistent results--with the |
---|
| 1081 | exception that the value seems to have the wrong type. *Don't try to |
---|
| 1082 | access an element of the array.* It doesn't have any elements. The |
---|
| 1083 | array "address" may not be the address of actual storage. |
---|
| 1084 | |
---|
| 1085 | The fact that the symbol is an array may lead to warnings where the |
---|
| 1086 | variable is used. Insert type casts to avoid the warnings. Here is an |
---|
| 1087 | example; it takes advantage of the ANSI C feature allowing macros that |
---|
| 1088 | expand to use the same name as the macro itself. |
---|
| 1089 | |
---|
| 1090 | GLOBALVALUEREF (int, ss$_normal); |
---|
| 1091 | GLOBALVALUEDEF (int, xyzzy,123); |
---|
| 1092 | #ifdef __GNUC__ |
---|
| 1093 | #define ss$_normal ((int) ss$_normal) |
---|
| 1094 | #define xyzzy ((int) xyzzy) |
---|
| 1095 | #endif |
---|
| 1096 | |
---|
| 1097 | Don't use `globaldef' or `globalref' with a variable whose type is |
---|
| 1098 | an enumeration type; this is not implemented. Instead, make the |
---|
| 1099 | variable an integer, and use a `globalvaluedef' for each of the |
---|
| 1100 | enumeration values. An example of this would be: |
---|
| 1101 | |
---|
| 1102 | #ifdef __GNUC__ |
---|
| 1103 | GLOBALDEF (int, color, 0); |
---|
| 1104 | GLOBALVALUEDEF (int, RED, 0); |
---|
| 1105 | GLOBALVALUEDEF (int, BLUE, 1); |
---|
| 1106 | GLOBALVALUEDEF (int, GREEN, 3); |
---|
| 1107 | #else |
---|
| 1108 | enum globaldef color {RED, BLUE, GREEN = 3}; |
---|
| 1109 | #endif |
---|
| 1110 | |
---|