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