![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-12 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to gcc.info-12 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.9 ! root 1: This is Info file gcc.info, produced by Makeinfo version 1.67 from the ! 2: input file gcc.texi. 1.1 root 3: 4: This file documents the use and the internals of the GNU compiler. 5: 1.1.1.8 root 6: Published by the Free Software Foundation 59 Temple Place - Suite 330 7: Boston, MA 02111-1307 USA 1.1.1.5 root 8: 1.1.1.8 root 9: Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software 10: Foundation, Inc. 1.1 root 11: 1.1.1.3 root 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. 1.1 root 15: 16: Permission is granted to copy and distribute modified versions of 17: this manual under the conditions for verbatim copying, provided also 1.1.1.7 root 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. 1.1 root 23: 24: Permission is granted to copy and distribute translations of this 25: manual into another language, under the above conditions for modified 1.1.1.3 root 26: versions, except that the sections entitled "GNU General Public 1.1.1.7 root 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. 1.1.1.3 root 31: 32: 1.1.1.8 root 33: File: gcc.info, Node: Temporaries, Prev: Static Definitions, Up: C++ Misunderstandings 1.1.1.6 root 34: 1.1.1.8 root 35: Temporaries May Vanish Before You Expect 36: ---------------------------------------- 1.1.1.6 root 37: 1.1.1.8 root 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. 1.1.1.6 root 353: 354: 1.1.1.8 root 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: ************** 1.1.1.6 root 396: 1.1.1.8 root 397: Your bug reports play an essential role in making GNU CC reliable. 1.1.1.6 root 398: 1.1.1.8 root 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. 1.1.1.7 root 416: 417: * Menu: 418: 1.1.1.8 root 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. 1.1.1.6 root 425: 426: 1.1.1.8 root 427: File: gcc.info, Node: Bug Criteria, Next: Bug Lists, Up: Bugs 1.1.1.6 root 428: 1.1.1.8 root 429: Have You Found a Bug? 430: ===================== 1.1.1.6 root 431: 1.1.1.8 root 432: If you are not sure whether you have found a bug, here are some 433: guidelines: 1.1.1.6 root 434: 1.1.1.8 root 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. 1.1.1.6 root 481: 482: 1.1.1.8 root 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 `[email protected]'. 1.1.1.6 root 489: 1.1.1.8 root 490: Send bug reports for GNU C++ to `[email protected]'. If your 491: bug involves the C++ class library libg++, send mail to 492: `[email protected]'. If you're not sure, you can send the 493: bug report to both lists. 494: 495: *Do not send bug reports to `[email protected]' 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 1.1.1.7 root 522: ================== 1.1.1.6 root 523: 1.1.1.8 root 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. 1.1.1.6 root 772: 773: 1.1.1.8 root 774: File: gcc.info, Node: Sending Patches, Prev: Bug Reporting, Up: Bugs 1.1.1.6 root 775: 1.1.1.8 root 776: Sending Patches for GNU CC 1.1.1.7 root 777: ========================== 1.1.1.6 root 778: 1.1.1.8 root 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, `[email protected]'. 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: `[email protected]', and if that brings no response, try 899: `[email protected]'. 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. 1.1.1.6 root 904: 905: 1.1.1.8 root 906: File: gcc.info, Node: VMS, Next: Portability, Prev: Service, Up: Top 1.1.1.6 root 907: 1.1.1.8 root 908: Using GNU CC on VMS 909: ******************* 1.1.1.6 root 910: 1.1.1.8 root 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. 1.1.1.3 root 919: 920: 1.1.1.8 root 921: File: gcc.info, Node: Include Files and VMS, Next: Global Declarations, Up: VMS 1.1.1.3 root 922: 1.1.1.8 root 923: Include Files and VMS 924: ===================== 1.1.1.3 root 925: 1.1.1.8 root 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 1.1.1.5 root 1008: 1.1.1.8 root 1009: Global Declarations and VMS 1010: =========================== 1.1.1.3 root 1011: 1.1.1.8 root 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 1.1.1.3 root 1110:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.