![[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.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.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: Asm Labels, Next: Explicit Reg Vars, Prev: Extended Asm, Up: C Extensions
1.1.1.6 root 34:
1.1.1.8 ! root 35: Controlling Names Used in Assembler Code
! 36: ========================================
1.1.1.7 root 37:
1.1.1.8 ! root 38: You can specify the name to be used in the assembler code for a C
! 39: function or variable by writing the `asm' (or `__asm__') keyword after
! 40: the declarator as follows:
! 41:
! 42: int foo asm ("myfoo") = 2;
! 43:
! 44: This specifies that the name to be used for the variable `foo' in the
! 45: assembler code should be `myfoo' rather than the usual `_foo'.
! 46:
! 47: On systems where an underscore is normally prepended to the name of
! 48: a C function or variable, this feature allows you to define names for
! 49: the linker that do not start with an underscore.
! 50:
! 51: You cannot use `asm' in this way in a function *definition*; but you
! 52: can get the same effect by writing a declaration for the function
! 53: before its definition and putting `asm' there, like this:
! 54:
! 55: extern func () asm ("FUNC");
! 56:
! 57: func (x, y)
! 58: int x, y;
! 59: ...
! 60:
! 61: It is up to you to make sure that the assembler names you choose do
! 62: not conflict with any other assembler symbols. Also, you must not use a
! 63: register name; that would produce completely invalid assembler code.
! 64: GNU CC does not as yet have the ability to store static variables in
! 65: registers. Perhaps that will be added.
! 66:
! 67:
! 68: File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: C Extensions
! 69:
! 70: Variables in Specified Registers
! 71: ================================
! 72:
! 73: GNU C allows you to put a few global variables into specified
! 74: hardware registers. You can also specify the register in which an
! 75: ordinary register variable should be allocated.
! 76:
! 77: * Global register variables reserve registers throughout the program.
! 78: This may be useful in programs such as programming language
! 79: interpreters which have a couple of global variables that are
! 80: accessed very often.
! 81:
! 82: * Local register variables in specific registers do not reserve the
! 83: registers. The compiler's data flow analysis is capable of
! 84: determining where the specified registers contain live values, and
! 85: where they are available for other uses.
! 86:
! 87: These local variables are sometimes convenient for use with the
! 88: extended `asm' feature (*note Extended Asm::.), if you want to
! 89: write one output of the assembler instruction directly into a
! 90: particular register. (This will work provided the register you
! 91: specify fits the constraints specified for that operand in the
! 92: `asm'.)
1.1.1.7 root 93:
1.1.1.8 ! root 94: * Menu:
1.1.1.7 root 95:
1.1.1.8 ! root 96: * Global Reg Vars::
! 97: * Local Reg Vars::
1.1.1.7 root 98:
99:
1.1.1.8 ! root 100: File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Up: Explicit Reg Vars
1.1.1.7 root 101:
1.1.1.8 ! root 102: Defining Global Register Variables
! 103: ----------------------------------
1.1.1.7 root 104:
1.1.1.8 ! root 105: You can define a global register variable in GNU C like this:
! 106:
! 107: register int *foo asm ("a5");
! 108:
! 109: Here `a5' is the name of the register which should be used. Choose a
! 110: register which is normally saved and restored by function calls on your
! 111: machine, so that library routines will not clobber it.
! 112:
! 113: Naturally the register name is cpu-dependent, so you would need to
! 114: conditionalize your program according to cpu type. The register `a5'
! 115: would be a good choice on a 68000 for a variable of pointer type. On
! 116: machines with register windows, be sure to choose a "global" register
! 117: that is not affected magically by the function call mechanism.
! 118:
! 119: In addition, operating systems on one type of cpu may differ in how
! 120: they name the registers; then you would need additional conditionals.
! 121: For example, some 68000 operating systems call this register `%a5'.
! 122:
! 123: Eventually there may be a way of asking the compiler to choose a
! 124: register automatically, but first we need to figure out how it should
! 125: choose and how to enable you to guide the choice. No solution is
! 126: evident.
! 127:
! 128: Defining a global register variable in a certain register reserves
! 129: that register entirely for this use, at least within the current
! 130: compilation. The register will not be allocated for any other purpose
! 131: in the functions in the current compilation. The register will not be
! 132: saved and restored by these functions. Stores into this register are
! 133: never deleted even if they would appear to be dead, but references may
! 134: be deleted or moved or simplified.
! 135:
! 136: It is not safe to access the global register variables from signal
! 137: handlers, or from more than one thread of control, because the system
! 138: library routines may temporarily use the register for other things
! 139: (unless you recompile them specially for the task at hand).
! 140:
! 141: It is not safe for one function that uses a global register variable
! 142: to call another such function `foo' by way of a third function `lose'
! 143: that was compiled without knowledge of this variable (i.e. in a
! 144: different source file in which the variable wasn't declared). This is
! 145: because `lose' might save the register and put some other value there.
! 146: For example, you can't expect a global register variable to be
! 147: available in the comparison-function that you pass to `qsort', since
! 148: `qsort' might have put something else in that register. (If you are
! 149: prepared to recompile `qsort' with the same global register variable,
! 150: you can solve this problem.)
! 151:
! 152: If you want to recompile `qsort' or other source files which do not
! 153: actually use your global register variable, so that they will not use
! 154: that register for any other purpose, then it suffices to specify the
! 155: compiler option `-ffixed-REG'. You need not actually add a global
! 156: register declaration to their source code.
! 157:
! 158: A function which can alter the value of a global register variable
! 159: cannot safely be called from a function compiled without this variable,
! 160: because it could clobber the value the caller expects to find there on
! 161: return. Therefore, the function which is the entry point into the part
! 162: of the program that uses the global register variable must explicitly
! 163: save and restore the value which belongs to its caller.
! 164:
! 165: On most machines, `longjmp' will restore to each global register
! 166: variable the value it had at the time of the `setjmp'. On some
! 167: machines, however, `longjmp' will not change the value of global
! 168: register variables. To be portable, the function that called `setjmp'
! 169: should make other arrangements to save the values of the global register
! 170: variables, and to restore them in a `longjmp'. This way, the same
! 171: thing will happen regardless of what `longjmp' does.
! 172:
! 173: All global register variable declarations must precede all function
! 174: definitions. If such a declaration could appear after function
! 175: definitions, the declaration would be too late to prevent the register
! 176: from being used for other purposes in the preceding functions.
! 177:
! 178: Global register variables may not have initial values, because an
! 179: executable file has no means to supply initial contents for a register.
! 180:
! 181: On the Sparc, there are reports that g3 ... g7 are suitable
! 182: registers, but certain library functions, such as `getwd', as well as
! 183: the subroutines for division and remainder, modify g3 and g4. g1 and
! 184: g2 are local temporaries.
1.1.1.7 root 185:
1.1.1.8 ! root 186: On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. Of
! 187: course, it will not do to use more than a few of those.
1.1.1.7 root 188:
1.1.1.8 ! root 189:
! 190: File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars
1.1.1.7 root 191:
1.1.1.8 ! root 192: Specifying Registers for Local Variables
! 193: ----------------------------------------
1.1.1.7 root 194:
1.1.1.8 ! root 195: You can define a local register variable with a specified register
! 196: like this:
1.1.1.7 root 197:
1.1.1.8 ! root 198: register int *foo asm ("a5");
1.1.1.7 root 199:
1.1.1.8 ! root 200: Here `a5' is the name of the register which should be used. Note that
! 201: this is the same syntax used for defining global register variables,
! 202: but for a local variable it would appear within a function.
1.1.1.7 root 203:
1.1.1.8 ! root 204: Naturally the register name is cpu-dependent, but this is not a
! 205: problem, since specific registers are most often useful with explicit
! 206: assembler instructions (*note Extended Asm::.). Both of these things
! 207: generally require that you conditionalize your program according to cpu
! 208: type.
1.1.1.7 root 209:
1.1.1.8 ! root 210: In addition, operating systems on one type of cpu may differ in how
! 211: they name the registers; then you would need additional conditionals.
! 212: For example, some 68000 operating systems call this register `%a5'.
1.1.1.7 root 213:
1.1.1.8 ! root 214: Eventually there may be a way of asking the compiler to choose a
! 215: register automatically, but first we need to figure out how it should
! 216: choose and how to enable you to guide the choice. No solution is
! 217: evident.
1.1.1.7 root 218:
1.1.1.8 ! root 219: Defining such a register variable does not reserve the register; it
! 220: remains available for other uses in places where flow control determines
! 221: the variable's value is not live. However, these registers are made
! 222: unavailable for use in the reload pass. I would not be surprised if
! 223: excessive use of this feature leaves the compiler too few available
! 224: registers to compile certain functions.
1.1.1.7 root 225:
226:
1.1.1.8 ! root 227: File: gcc.info, Node: Alternate Keywords, Next: Incomplete Enums, Prev: Explicit Reg Vars, Up: C Extensions
1.1.1.7 root 228:
1.1.1.8 ! root 229: Alternate Keywords
1.1.1.6 root 230: ==================
231:
1.1.1.8 ! root 232: The option `-traditional' disables certain keywords; `-ansi'
! 233: disables certain others. This causes trouble when you want to use GNU C
! 234: extensions, or ANSI C features, in a general-purpose header file that
! 235: should be usable by all programs, including ANSI C programs and
! 236: traditional ones. The keywords `asm', `typeof' and `inline' cannot be
! 237: used since they won't work in a program compiled with `-ansi', while
! 238: the keywords `const', `volatile', `signed', `typeof' and `inline' won't
! 239: work in a program compiled with `-traditional'.
! 240:
! 241: The way to solve these problems is to put `__' at the beginning and
! 242: end of each problematical keyword. For example, use `__asm__' instead
! 243: of `asm', `__const__' instead of `const', and `__inline__' instead of
! 244: `inline'.
! 245:
! 246: Other C compilers won't accept these alternative keywords; if you
! 247: want to compile with another compiler, you can define the alternate
! 248: keywords as macros to replace them with the customary keywords. It
! 249: looks like this:
! 250:
! 251: #ifndef __GNUC__
! 252: #define __asm__ asm
! 253: #endif
! 254:
! 255: `-pedantic' causes warnings for many GNU C extensions. You can
! 256: prevent such warnings within one expression by writing `__extension__'
! 257: before the expression. `__extension__' has no effect aside from this.
! 258:
! 259:
! 260: File: gcc.info, Node: Incomplete Enums, Next: Function Names, Prev: Alternate Keywords, Up: C Extensions
! 261:
! 262: Incomplete `enum' Types
! 263: =======================
! 264:
! 265: You can define an `enum' tag without specifying its possible values.
! 266: This results in an incomplete type, much like what you get if you write
! 267: `struct foo' without describing the elements. A later declaration
! 268: which does specify the possible values completes the type.
! 269:
! 270: You can't allocate variables or storage using the type while it is
! 271: incomplete. However, you can work with pointers to that type.
! 272:
! 273: This extension may not be very useful, but it makes the handling of
! 274: `enum' more consistent with the way `struct' and `union' are handled.
! 275:
! 276: This extension is not supported by GNU C++.
! 277:
! 278:
! 279: File: gcc.info, Node: Function Names, Prev: Incomplete Enums, Up: C Extensions
! 280:
! 281: Function Names as Strings
! 282: =========================
! 283:
! 284: GNU CC predefines two string variables to be the name of the current
! 285: function. The variable `__FUNCTION__' is the name of the function as
! 286: it appears in the source. The variable `__PRETTY_FUNCTION__' is the
! 287: name of the function pretty printed in a language specific fashion.
! 288:
! 289: These names are always the same in a C function, but in a C++
! 290: function they may be different. For example, this program:
! 291:
! 292: extern "C" {
! 293: extern int printf (char *, ...);
! 294: }
! 295:
! 296: class a {
! 297: public:
! 298: sub (int i)
! 299: {
! 300: printf ("__FUNCTION__ = %s\n", __FUNCTION__);
! 301: printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
! 302: }
! 303: };
! 304:
! 305: int
! 306: main (void)
! 307: {
! 308: a ax;
! 309: ax.sub (0);
! 310: return 0;
! 311: }
! 312:
! 313: gives this output:
! 314:
! 315: __FUNCTION__ = sub
! 316: __PRETTY_FUNCTION__ = int a::sub (int)
! 317:
! 318: These names are not macros: they are predefined string variables.
! 319: For example, `#ifdef __FUNCTION__' does not have any special meaning
! 320: inside a function, since the preprocessor does not do anything special
! 321: with the identifier `__FUNCTION__'.
! 322:
! 323:
! 324: File: gcc.info, Node: C++ Extensions, Next: Trouble, Prev: C Extensions, Up: Top
! 325:
! 326: Extensions to the C++ Language
! 327: ******************************
! 328:
! 329: The GNU compiler provides these extensions to the C++ language (and
! 330: you can also use most of the C language extensions in your C++
! 331: programs). If you want to write code that checks whether these
! 332: features are available, you can test for the GNU compiler the same way
! 333: as for C programs: check for a predefined macro `__GNUC__'. You can
! 334: also use `__GNUG__' to test specifically for GNU C++ (*note Standard
! 335: Predefined Macros: (cpp.info)Standard Predefined.).
1.1.1.7 root 336:
337: * Menu:
338:
1.1.1.8 ! root 339: * Naming Results:: Giving a name to C++ function return values.
! 340: * Min and Max:: C++ Minimum and maximum operators.
! 341: * Destructors and Goto:: Goto is safe to use in C++ even when destructors
! 342: are needed.
! 343: * C++ Interface:: You can use a single C++ header file for both
! 344: declarations and definitions.
! 345: * Template Instantiation:: Methods for ensuring that exactly one copy of
! 346: each needed template instantiation is emitted.
! 347: * C++ Signatures:: You can specify abstract types to get subtype
! 348: polymorphism independent from inheritance.
! 349:
! 350:
! 351: File: gcc.info, Node: Naming Results, Next: Min and Max, Up: C++ Extensions
! 352:
! 353: Named Return Values in C++
! 354: ==========================
! 355:
! 356: GNU C++ extends the function-definition syntax to allow you to
! 357: specify a name for the result of a function outside the body of the
! 358: definition, in C++ programs:
1.1.1.6 root 359:
1.1.1.8 ! root 360: TYPE
! 361: FUNCTIONNAME (ARGS) return RESULTNAME;
1.1.1.5 root 362: {
363: ...
1.1.1.8 ! root 364: BODY
! 365: ...
! 366: }
1.1.1.7 root 367:
1.1.1.8 ! root 368: You can use this feature to avoid an extra constructor call when a
! 369: function result has a class type. For example, consider a function
! 370: `m', declared as `X v = m ();', whose result is of class `X':
1.1.1.7 root 371:
1.1.1.8 ! root 372: X
! 373: m ()
! 374: {
! 375: X b;
! 376: b.a = 23;
! 377: return b;
! 378: }
! 379:
! 380: Although `m' appears to have no arguments, in fact it has one
! 381: implicit argument: the address of the return value. At invocation, the
! 382: address of enough space to hold `v' is sent in as the implicit argument.
! 383: Then `b' is constructed and its `a' field is set to the value 23.
! 384: Finally, a copy constructor (a constructor of the form `X(X&)') is
! 385: applied to `b', with the (implicit) return value location as the
! 386: target, so that `v' is now bound to the return value.
! 387:
! 388: But this is wasteful. The local `b' is declared just to hold
! 389: something that will be copied right out. While a compiler that
! 390: combined an "elision" algorithm with interprocedural data flow analysis
! 391: could conceivably eliminate all of this, it is much more practical to
! 392: allow you to assist the compiler in generating efficient code by
! 393: manipulating the return value explicitly, thus avoiding the local
! 394: variable and copy constructor altogether.
! 395:
! 396: Using the extended GNU C++ function-definition syntax, you can avoid
! 397: the temporary allocation and copying by naming `r' as your return value
! 398: at the outset, and assigning to its `a' field directly:
1.1.1.7 root 399:
1.1.1.8 ! root 400: X
! 401: m () return r;
! 402: {
! 403: r.a = 23;
! 404: }
1.1.1.7 root 405:
1.1.1.8 ! root 406: The declaration of `r' is a standard, proper declaration, whose effects
! 407: are executed *before* any of the body of `m'.
1.1.1.7 root 408:
1.1.1.8 ! root 409: Functions of this type impose no additional restrictions; in
! 410: particular, you can execute `return' statements, or return implicitly by
! 411: reaching the end of the function body ("falling off the edge"). Cases
! 412: like
1.1.1.7 root 413:
1.1.1.8 ! root 414: X
! 415: m () return r (23);
! 416: {
! 417: return;
! 418: }
1.1.1.7 root 419:
1.1.1.8 ! root 420: (or even `X m () return r (23); { }') are unambiguous, since the return
! 421: value `r' has been initialized in either case. The following code may
! 422: be hard to read, but also works predictably:
1.1.1.7 root 423:
1.1.1.8 ! root 424: X
! 425: m () return r;
! 426: {
! 427: X b;
! 428: return b;
! 429: }
! 430:
! 431: The return value slot denoted by `r' is initialized at the outset,
! 432: but the statement `return b;' overrides this value. The compiler deals
! 433: with this by destroying `r' (calling the destructor if there is one, or
! 434: doing nothing if there is not), and then reinitializing `r' with `b'.
! 435:
! 436: This extension is provided primarily to help people who use
! 437: overloaded operators, where there is a great need to control not just
! 438: the arguments, but the return values of functions. For classes where
! 439: the copy constructor incurs a heavy performance penalty (especially in
! 440: the common case where there is a quick default constructor), this is a
! 441: major savings. The disadvantage of this extension is that you do not
! 442: control when the default constructor for the return value is called: it
! 443: is always called at the beginning.
! 444:
! 445:
! 446: File: gcc.info, Node: Min and Max, Next: Destructors and Goto, Prev: Naming Results, Up: C++ Extensions
! 447:
! 448: Minimum and Maximum Operators in C++
! 449: ====================================
! 450:
! 451: It is very convenient to have operators which return the "minimum"
! 452: or the "maximum" of two arguments. In GNU C++ (but not in GNU C),
! 453:
! 454: `A <? B'
! 455: is the "minimum", returning the smaller of the numeric values A
! 456: and B;
! 457:
! 458: `A >? B'
! 459: is the "maximum", returning the larger of the numeric values A and
! 460: B.
! 461:
! 462: These operations are not primitive in ordinary C++, since you can
! 463: use a macro to return the minimum of two things in C++, as in the
! 464: following example.
! 465:
! 466: #define MIN(X,Y) ((X) < (Y) ? : (X) : (Y))
! 467:
! 468: You might then use `int min = MIN (i, j);' to set MIN to the minimum
! 469: value of variables I and J.
! 470:
! 471: However, side effects in `X' or `Y' may cause unintended behavior.
! 472: For example, `MIN (i++, j++)' will fail, incrementing the smaller
! 473: counter twice. A GNU C extension allows you to write safe macros that
! 474: avoid this kind of problem (*note Naming an Expression's Type: Naming
! 475: Types.). However, writing `MIN' and `MAX' as macros also forces you to
! 476: use function-call notation notation for a fundamental arithmetic
! 477: operation. Using GNU C++ extensions, you can write `int min = i <? j;'
! 478: instead.
! 479:
! 480: Since `<?' and `>?' are built into the compiler, they properly
! 481: handle expressions with side-effects; `int min = i++ <? j++;' works
! 482: correctly.
! 483:
! 484:
! 485: File: gcc.info, Node: Destructors and Goto, Next: C++ Interface, Prev: Min and Max, Up: C++ Extensions
! 486:
! 487: `goto' and Destructors in GNU C++
! 488: =================================
! 489:
! 490: In C++ programs, you can safely use the `goto' statement. When you
! 491: use it to exit a block which contains aggregates requiring destructors,
! 492: the destructors will run before the `goto' transfers control. (In ANSI
! 493: C++, `goto' is restricted to targets within the current block.)
! 494:
! 495: The compiler still forbids using `goto' to *enter* a scope that
! 496: requires constructors.
! 497:
! 498:
! 499: File: gcc.info, Node: C++ Interface, Next: Template Instantiation, Prev: Destructors and Goto, Up: C++ Extensions
! 500:
! 501: Declarations and Definitions in One Header
! 502: ==========================================
! 503:
! 504: C++ object definitions can be quite complex. In principle, your
! 505: source code will need two kinds of things for each object that you use
! 506: across more than one source file. First, you need an "interface"
! 507: specification, describing its structure with type declarations and
! 508: function prototypes. Second, you need the "implementation" itself. It
! 509: can be tedious to maintain a separate interface description in a header
! 510: file, in parallel to the actual implementation. It is also dangerous,
! 511: since separate interface and implementation definitions may not remain
! 512: parallel.
! 513:
! 514: With GNU C++, you can use a single header file for both purposes.
! 515:
! 516: *Warning:* The mechanism to specify this is in transition. For the
! 517: nonce, you must use one of two `#pragma' commands; in a future
! 518: release of GNU C++, an alternative mechanism will make these
! 519: `#pragma' commands unnecessary.
! 520:
! 521: The header file contains the full definitions, but is marked with
! 522: `#pragma interface' in the source code. This allows the compiler to
! 523: use the header file only as an interface specification when ordinary
! 524: source files incorporate it with `#include'. In the single source file
! 525: where the full implementation belongs, you can use either a naming
! 526: convention or `#pragma implementation' to indicate this alternate use
! 527: of the header file.
! 528:
! 529: `#pragma interface'
! 530: `#pragma interface "SUBDIR/OBJECTS.h"'
! 531: Use this directive in *header files* that define object classes,
! 532: to save space in most of the object files that use those classes.
! 533: Normally, local copies of certain information (backup copies of
! 534: inline member functions, debugging information, and the internal
! 535: tables that implement virtual functions) must be kept in each
! 536: object file that includes class definitions. You can use this
! 537: pragma to avoid such duplication. When a header file containing
! 538: `#pragma interface' is included in a compilation, this auxiliary
! 539: information will not be generated (unless the main input source
! 540: file itself uses `#pragma implementation'). Instead, the object
! 541: files will contain references to be resolved at link time.
! 542:
! 543: The second form of this directive is useful for the case where you
! 544: have multiple headers with the same name in different directories.
! 545: If you use this form, you must specify the same string to `#pragma
! 546: implementation'.
! 547:
! 548: `#pragma implementation'
! 549: `#pragma implementation "OBJECTS.h"'
! 550: Use this pragma in a *main input file*, when you want full output
! 551: from included header files to be generated (and made globally
! 552: visible). The included header file, in turn, should use `#pragma
! 553: interface'. Backup copies of inline member functions, debugging
! 554: information, and the internal tables used to implement virtual
! 555: functions are all generated in implementation files.
! 556:
! 557: If you use `#pragma implementation' with no argument, it applies to
! 558: an include file with the same basename(1) as your source file.
! 559: For example, in `allclass.cc', `#pragma implementation' by itself
! 560: is equivalent to `#pragma implementation "allclass.h"'.
! 561:
! 562: In versions of GNU C++ prior to 2.6.0 `allclass.h' was treated as
! 563: an implementation file whenever you would include it from
! 564: `allclass.cc' even if you never specified `#pragma
! 565: implementation'. This was deemed to be more trouble than it was
! 566: worth, however, and disabled.
! 567:
! 568: If you use an explicit `#pragma implementation', it must appear in
! 569: your source file *before* you include the affected header files.
! 570:
! 571: Use the string argument if you want a single implementation file to
! 572: include code from multiple header files. (You must also use
! 573: `#include' to include the header file; `#pragma implementation'
! 574: only specifies how to use the file--it doesn't actually include
! 575: it.)
! 576:
! 577: There is no way to split up the contents of a single header file
! 578: into multiple implementation files.
! 579:
! 580: `#pragma implementation' and `#pragma interface' also have an effect
! 581: on function inlining.
! 582:
! 583: If you define a class in a header file marked with `#pragma
! 584: interface', the effect on a function defined in that class is similar to
! 585: an explicit `extern' declaration--the compiler emits no code at all to
! 586: define an independent version of the function. Its definition is used
! 587: only for inlining with its callers.
! 588:
! 589: Conversely, when you include the same header file in a main source
! 590: file that declares it as `#pragma implementation', the compiler emits
! 591: code for the function itself; this defines a version of the function
! 592: that can be found via pointers (or by callers compiled without
! 593: inlining). If all calls to the function can be inlined, you can avoid
! 594: emitting the function by compiling with `-fno-implement-inlines'. If
! 595: any calls were not inlined, you will get linker errors.
! 596:
! 597: ---------- Footnotes ----------
1.1.1.7 root 598:
1.1.1.8 ! root 599: (1) A file's "basename" was the name stripped of all leading path
! 600: information and of trailing suffixes, such as `.h' or `.C' or `.cc'.
1.1.1.7 root 601:
602:
1.1.1.8 ! root 603: File: gcc.info, Node: Template Instantiation, Next: C++ Signatures, Prev: C++ Interface, Up: C++ Extensions
1.1.1.7 root 604:
1.1.1.8 ! root 605: Where's the Template?
! 606: =====================
1.1.1.7 root 607:
1.1.1.8 ! root 608: C++ templates are the first language feature to require more
! 609: intelligence from the environment than one usually finds on a UNIX
! 610: system. Somehow the compiler and linker have to make sure that each
! 611: template instance occurs exactly once in the executable if it is needed,
! 612: and not at all otherwise. There are two basic approaches to this
! 613: problem, which I will refer to as the Borland model and the Cfront
! 614: model.
! 615:
! 616: Borland model
! 617: Borland C++ solved the template instantiation problem by adding
! 618: the code equivalent of common blocks to their linker; template
! 619: instances are emitted in each translation unit that uses them, and
! 620: they are collapsed together at run time. The advantage of this
! 621: model is that the linker only has to consider the object files
! 622: themselves; there is no external complexity to worry about. This
! 623: disadvantage is that compilation time is increased because the
! 624: template code is being compiled repeatedly. Code written for this
! 625: model tends to include definitions of all member templates in the
! 626: header file, since they must be seen to be compiled.
! 627:
! 628: Cfront model
! 629: The AT&T C++ translator, Cfront, solved the template instantiation
! 630: problem by creating the notion of a template repository, an
! 631: automatically maintained place where template instances are
! 632: stored. As individual object files are built, notes are placed in
! 633: the repository to record where templates and potential type
! 634: arguments were seen so that the subsequent instantiation step
! 635: knows where to find them. At link time, any needed instances are
! 636: generated and linked in. The advantages of this model are more
! 637: optimal compilation speed and the ability to use the system
! 638: linker; to implement the Borland model a compiler vendor also
! 639: needs to replace the linker. The disadvantages are vastly
! 640: increased complexity, and thus potential for error; theoretically,
! 641: this should be just as transparent, but in practice it has been
! 642: very difficult to build multiple programs in one directory and one
! 643: program in multiple directories using Cfront. Code written for
! 644: this model tends to separate definitions of non-inline member
! 645: templates into a separate file, which is magically found by the
! 646: link preprocessor when a template needs to be instantiated.
! 647:
! 648: Currently, g++ implements neither automatic model. In the mean time,
! 649: you have three options for dealing with template instantiations:
! 650:
! 651: 1. Do nothing. Pretend g++ does implement automatic instantiation
! 652: management. Code written for the Borland model will work fine, but
! 653: each translation unit will contain instances of each of the
! 654: templates it uses. In a large program, this can lead to an
! 655: unacceptable amount of code duplication.
! 656:
! 657: 2. Add `#pragma interface' to all files containing template
! 658: definitions. For each of these files, add `#pragma implementation
! 659: "FILENAME"' to the top of some `.C' file which `#include's it.
! 660: Then compile everything with -fexternal-templates. The templates
! 661: will then only be expanded in the translation unit which
! 662: implements them (i.e. has a `#pragma implementation' line for the
! 663: file where they live); all other files will use external
! 664: references. If you're lucky, everything should work properly. If
! 665: you get undefined symbol errors, you need to make sure that each
! 666: template instance which is used in the program is used in the file
! 667: which implements that template. If you don't have any use for a
! 668: particular instance in that file, you can just instantiate it
! 669: explicitly, using the syntax from the latest C++ working paper:
! 670:
! 671: template class A<int>;
! 672: template ostream& operator << (ostream&, const A<int>&);
! 673:
! 674: This strategy will work with code written for either model. If
! 675: you are using code written for the Cfront model, the file
! 676: containing a class template and the file containing its member
! 677: templates should be implemented in the same translation unit.
! 678:
! 679: A slight variation on this approach is to use the flag
! 680: -falt-external-templates instead; this flag causes template
! 681: instances to be emitted in the translation unit that implements
! 682: the header where they are first instantiated, rather than the one
! 683: which implements the file where the templates are defined. This
! 684: header must be the same in all translation units, or things are
! 685: likely to break.
! 686:
! 687: *Note Declarations and Definitions in One Header: C++ Interface,
! 688: for more discussion of these pragmas.
! 689:
! 690: 3. Explicitly instantiate all the template instances you use, and
! 691: compile with -fno-implicit-templates. This is probably your best
! 692: bet; it may require more knowledge of exactly which templates you
! 693: are using, but it's less mysterious than the previous approach,
! 694: and it doesn't require any `#pragma's or other g++-specific code.
! 695: You can scatter the instantiations throughout your program, you
! 696: can create one big file to do all the instantiations, or you can
! 697: create tiny files like
1.1.1.7 root 698:
1.1.1.8 ! root 699: #include "Foo.h"
! 700: #include "Foo.cc"
! 701:
! 702: template class Foo<int>;
1.1.1.7 root 703:
1.1.1.8 ! root 704: for each instance you need, and create a template instantiation
! 705: library from those. I'm partial to the last, but your mileage may
! 706: vary. If you are using Cfront-model code, you can probably get
! 707: away with not using -fno-implicit-templates when compiling files
! 708: that don't `#include' the member template definitions.
! 709:
! 710:
! 711: File: gcc.info, Node: C++ Signatures, Prev: Template Instantiation, Up: C++ Extensions
! 712:
! 713: Type Abstraction using Signatures
! 714: =================================
! 715:
! 716: In GNU C++, you can use the keyword `signature' to define a
! 717: completely abstract class interface as a datatype. You can connect this
! 718: abstraction with actual classes using signature pointers. If you want
! 719: to use signatures, run the GNU compiler with the `-fhandle-signatures'
! 720: command-line option. (With this option, the compiler reserves a second
! 721: keyword `sigof' as well, for a future extension.)
! 722:
! 723: Roughly, signatures are type abstractions or interfaces of classes.
! 724: Some other languages have similar facilities. C++ signatures are
! 725: related to ML's signatures, Haskell's type classes, definition modules
! 726: in Modula-2, interface modules in Modula-3, abstract types in Emerald,
! 727: type modules in Trellis/Owl, categories in Scratchpad II, and types in
! 728: POOL-I. For a more detailed discussion of signatures, see `Signatures:
! 729: A Language Extension for Improving Type Abstraction and Subtype
! 730: Polymorphism in C++' by Gerald Baumgartner and Vincent F. Russo (Tech
! 731: report CSD-TR-95-051, Dept. of Computer Sciences, Purdue University,
! 732: August 1995, a slightly improved version appeared in
! 733: *Software--Practice & Experience*, 25(8), pp. 863-889, August 1995).
! 734: You can get the tech report by anonymous FTP from `ftp.cs.purdue.edu'
! 735: in `pub/gb/Signature-design.ps.gz'.
! 736:
! 737: Syntactically, a signature declaration is a collection of member
! 738: function declarations and nested type declarations. For example, this
! 739: signature declaration defines a new abstract type `S' with member
! 740: functions `int foo ()' and `int bar (int)':
1.1.1.7 root 741:
1.1.1.8 ! root 742: signature S
! 743: {
! 744: int foo ();
! 745: int bar (int);
! 746: };
1.1.1.7 root 747:
1.1.1.8 ! root 748: Since signature types do not include implementation definitions, you
! 749: cannot write an instance of a signature directly. Instead, you can
! 750: define a pointer to any class that contains the required interfaces as a
! 751: "signature pointer". Such a class "implements" the signature type.
! 752:
! 753: To use a class as an implementation of `S', you must ensure that the
! 754: class has public member functions `int foo ()' and `int bar (int)'.
! 755: The class can have other member functions as well, public or not; as
! 756: long as it offers what's declared in the signature, it is suitable as
! 757: an implementation of that signature type.
! 758:
! 759: For example, suppose that `C' is a class that meets the requirements
! 760: of signature `S' (`C' "conforms to" `S'). Then
! 761:
! 762: C obj;
! 763: S * p = &obj;
! 764:
! 765: defines a signature pointer `p' and initializes it to point to an
! 766: object of type `C'. The member function call `int i = p->foo ();'
! 767: executes `obj.foo ()'.
! 768:
! 769: Abstract virtual classes provide somewhat similar facilities in
! 770: standard C++. There are two main advantages to using signatures
! 771: instead:
! 772:
! 773: 1. Subtyping becomes independent from inheritance. A class or
! 774: signature type `T' is a subtype of a signature type `S'
! 775: independent of any inheritance hierarchy as long as all the member
! 776: functions declared in `S' are also found in `T'. So you can
! 777: define a subtype hierarchy that is completely independent from any
! 778: inheritance (implementation) hierarchy, instead of being forced to
! 779: use types that mirror the class inheritance hierarchy.
! 780:
! 781: 2. Signatures allow you to work with existing class hierarchies as
! 782: implementations of a signature type. If those class hierarchies
! 783: are only available in compiled form, you're out of luck with
! 784: abstract virtual classes, since an abstract virtual class cannot
! 785: be retrofitted on top of existing class hierarchies. So you would
! 786: be required to write interface classes as subtypes of the abstract
! 787: virtual class.
! 788:
! 789: There is one more detail about signatures. A signature declaration
! 790: can contain member function *definitions* as well as member function
! 791: declarations. A signature member function with a full definition is
! 792: called a *default implementation*; classes need not contain that
! 793: particular interface in order to conform. For example, a class `C' can
! 794: conform to the signature
1.1.1.7 root 795:
1.1.1.8 ! root 796: signature T
! 797: {
! 798: int f (int);
! 799: int f0 () { return f (0); };
! 800: };
1.1.1.7 root 801:
1.1.1.8 ! root 802: whether or not `C' implements the member function `int f0 ()'. If you
! 803: define `C::f0', that definition takes precedence; otherwise, the
! 804: default implementation `S::f0' applies.
1.1.1.7 root 805:
1.1.1.8 ! root 806:
! 807: File: gcc.info, Node: Trouble, Next: Bugs, Prev: C++ Extensions, Up: Top
1.1.1.7 root 808:
1.1.1.8 ! root 809: Known Causes of Trouble with GNU CC
! 810: ***********************************
1.1.1.7 root 811:
1.1.1.8 ! root 812: This section describes known problems that affect users of GNU CC.
! 813: Most of these are not GNU CC bugs per se--if they were, we would fix
! 814: them. But the result for a user may be like the result of a bug.
1.1.1.7 root 815:
1.1.1.8 ! root 816: Some of these problems are due to bugs in other software, some are
! 817: missing features that are too much work to add, and some are places
! 818: where people's opinions differ as to what is best.
1.1.1.7 root 819:
820: * Menu:
821:
1.1.1.8 ! root 822: * Actual Bugs:: Bugs we will fix later.
! 823: * Installation Problems:: Problems that manifest when you install GNU CC.
! 824: * Cross-Compiler Problems:: Common problems of cross compiling with GNU CC.
! 825: * Interoperation:: Problems using GNU CC with other compilers,
! 826: and with certain linkers, assemblers and debuggers.
! 827: * External Bugs:: Problems compiling certain programs.
! 828: * Incompatibilities:: GNU CC is incompatible with traditional C.
! 829: * Fixed Headers:: GNU C uses corrected versions of system header files.
! 830: This is necessary, but doesn't always work smoothly.
! 831: * Standard Libraries:: GNU C uses the system C library, which might not be
! 832: compliant with the ISO/ANSI C standard.
! 833: * Disappointments:: Regrettable things we can't change, but not quite bugs.
! 834: * C++ Misunderstandings:: Common misunderstandings with GNU C++.
! 835: * Protoize Caveats:: Things to watch out for when using `protoize'.
! 836: * Non-bugs:: Things we think are right, but some others disagree.
! 837: * Warnings and Errors:: Which problems in your code get warnings,
! 838: and which get errors.
! 839:
! 840:
! 841: File: gcc.info, Node: Actual Bugs, Next: Installation Problems, Up: Trouble
! 842:
! 843: Actual Bugs We Haven't Fixed Yet
! 844: ================================
! 845:
! 846: * The `fixincludes' script interacts badly with automounters; if the
! 847: directory of system header files is automounted, it tends to be
! 848: unmounted while `fixincludes' is running. This would seem to be a
! 849: bug in the automounter. We don't know any good way to work around
! 850: it.
! 851:
! 852: * The `fixproto' script will sometimes add prototypes for the
! 853: `sigsetjmp' and `siglongjmp' functions that reference the
! 854: `jmp_buf' type before that type is defined. To work around this,
! 855: edit the offending file and place the typedef in front of the
! 856: prototypes.
! 857:
! 858: * There are several obscure case of mis-using struct, union, and
! 859: enum tags that are not detected as errors by the compiler.
! 860:
! 861: * When `-pedantic-errors' is specified, GNU C will incorrectly give
! 862: an error message when a function name is specified in an expression
! 863: involving the comma operator.
! 864:
! 865: * Loop unrolling doesn't work properly for certain C++ programs.
! 866: This is a bug in the C++ front end. It sometimes emits incorrect
! 867: debug info, and the loop unrolling code is unable to recover from
! 868: this error.
1.1.1.2 root 869:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.