Return to README.macros CVS log

Up to [local] / OpenXM_contrib2 / asir2000 / gc / doc

Annotation of OpenXM_contrib2/asir2000/gc/doc/README.macros, Revision 1.2

1.1       noro        1: The collector uses a large amount of conditional compilation in order to
                      2: deal with platform dependencies.  This violates a number of known coding
                      3: standards.  On the other hand, it seems to be the only practical way to
                      4: support this many platforms without excessive code duplication.
                      5:
                      6: A few guidelines have mostly been followed in order to keep this manageable:
                      7:
                      8: 1) #if and #ifdef directives are properly indented whenever easily possible.
                      9: All known C compilers allow whitespace between the "#" and the "if" to make
                     10: this possible.  ANSI C also allows white space before the "#", though we
                     11: avoid that.  It has the known disadvantages that it differs from the normal
                     12: GNU conventions, and that it makes patches larger than otherwise necessary.
                     13: In my opinion, it's still well worth it, for the same reason that we indent
                     14: ordinary "if" statements.
                     15:
                     16: 2) Whenever possible, tests are performed on the macros defined in gcconfig.h
                     17: instead of directly testing patform-specific predefined macros.  This makes it
                     18: relatively easy to adapt to new compilers with a different set of predefined
                     19: macros.  Currently these macros generally identify platforms instead of
                     20: features.  In many cases, this is a mistake.
                     21:
                     22: 3) The code currently avoids #elif, eventhough that would make it more
                     23: readable.  This was done since #elif would need to be understood by ALL
                     24: compilers used to build the collector, and that hasn't always been the case.
                     25: It makes sense to reconsider this decision at some point, since #elif has been
                     26: standardized at least since 1989.
                     27:
                     28: Many of the tested configuration macros are at least somewhat defined in
                     29: either include/private/gcconfig.h or in Makefile.direct.  Here is an attempt
                     30: at defining some of the remainder:  (Thanks to Walter Bright for suggesting
                     31: this.  This is a work in progress)
                     32:
                     33: MACRO          EXPLANATION
                     34: -----          -----------
                     35:
                     36: __DMC__        Always #define'd by the Digital Mars compiler. Expands
                     37:                to the compiler version number in hex, i.e. 0x810 is
                     38:                version 8.1b0
                     39:
                     40: _ENABLE_ARRAYNEW
                     41:                #define'd by the Digital Mars C++ compiler when
                     42:                operator new[] and delete[] are separately
                     43:                overloadable. Used in gc_cpp.h.
                     44:
                     45: _MSC_VER       Expands to the Visual C++ compiler version.  Assumed to
                     46:                not be defined for other compilers (at least if they behave
                     47:                appreciably differently).
                     48:
                     49: _DLL           Defined by Visual C++ if dynamic libraries are being built
                     50:                or used.  Used to test whether __declspec(dllimport) or
                     51:                __declspec(dllexport) needs to be added to declarations
                     52:                to support the case in which the collector is in a dll.
                     53:
1.2     ! noro       54: GC_DLL         User-settable macro that forces the effect of _DLL.  Set
        !            55:                by gc.h if _DLL is defined and GC_NOT_DLL is undefined.
        !            56:                This is the macro that is tested internally to determine
        !            57:                whether the GC is in its own dynamic library.  May need
        !            58:                to be set by clients before including gc.h.  Note that
        !            59:                inside the GC implementation it indicates that the
        !            60:                collector is in its own dynamic library, should export
        !            61:                its symbols, etc.  But in clients it indicates that the
        !            62:                GC resides in a different DLL, its entry points should
        !            63:                be referenced accordingly, and precautions may need to
        !            64:                be taken to properly deal with statically allocated
        !            65:                variables in the main program.  Used only for MS Windows.
1.1       noro       66:
                     67: GC_NOT_DLL     User-settable macro that overrides _DLL, e.g. if dynamic
                     68:                libraries are used, but the collector is in a static library.
                     69:
                     70: __STDC__       Assumed to be defined only by compilers that understand
                     71:                prototypes and other C89 features.  Its value is generally
                     72:                not used, since we are fine with most nonconforming extensions.
                     73:
                     74: SUNOS5SIGS     Solaris-like signal handling.  This is probably misnamed,
                     75:                since it really doesn't guarantee much more than Posix.
                     76:                Currently set only for Solaris2.X, HPUX, and DRSNX.  Should
                     77:                probably be set for some other platforms.
                     78:
                     79: PCR            Set if the collector is being built as part of the Xerox
                     80:                Portable Common Runtime.
                     81:
                     82: SRC_M3         Set if the collector is being built as a replacement of the
                     83:                one in the DEC/Compaq SRC Modula-3 runtime.  I suspect this
                     84:                was last used around 1994, and no doubt broke a long time ago.
                     85:                It's there primarily incase someone wants to port to a similar
                     86:                system.
                     87:
                     88:
                     89: