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