src/mm/boehm-gc/doc/README.macros

   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 Many of the tested configuration macros are at least somewhat defined in
  23 either include/private/gcconfig.h or in Makefile.direct.  Here is an attempt
  24 at defining some of the remainder:  (Thanks to Walter Bright for suggesting
  25 this.  This is a work in progress)
  26
  27 MACRO           EXPLANATION
  28 -----           -----------
  29
  30 GC_DEBUG        Tested by gc.h.  Causes all-upper-case macros to
  31                 expand to calls to debug versions of collector routines.
  32
  33 GC_NO_THREAD_REDIRECTS Tested by gc.h.  Prevents redirection of thread
  34                 creation routines etc. to GC_ versions.  Requires the
  35                 programmer to explicitly handle thread registration.
  36
  37 GC_NO_THREAD_DECLS Tested by gc.h. MS Windows only.  Do not declare
  38                 Windows thread creation routines and do not include windows.h.
  39
  40 __DMC__ Always #define'd by the Digital Mars compiler. Expands
  41                 to the compiler version number in hex, i.e. 0x810 is
  42                 version 8.1b0
  43
  44 _ENABLE_ARRAYNEW
  45                 #define'd by the Digital Mars C++ compiler when
  46                 operator new[] and delete[] are separately
  47                 overloadable. Used in gc_cpp.h.
  48
  49 _MSC_VER        Expands to the Visual C++ compiler version.  Assumed to
  50                 not be defined for other compilers (at least if they behave
  51                 appreciably differently).
  52
  53 _DLL            Defined by Visual C++ if dynamic libraries are being built
  54                 or used.  Used to test whether __declspec(dllimport) or
  55                 __declspec(dllexport) needs to be added to declarations
  56                 to support the case in which the collector is in a dll.
  57
  58 GC_DLL          User-settable macro that forces the effect of _DLL.  Set
  59                 by gc.h if _DLL is defined and GC_NOT_DLL is undefined.
  60                 This is the macro that is tested internally to determine
  61                 whether the GC is in its own dynamic library.  May need
  62                 to be set by clients before including gc.h.  Note that
  63                 inside the GC implementation it indicates that the
  64                 collector is in its own dynamic library, should export
  65                 its symbols, etc.  But in clients it indicates that the
  66                 GC resides in a different DLL, its entry points should
  67                 be referenced accordingly, and precautions may need to
  68                 be taken to properly deal with statically allocated
  69                 variables in the main program.  Used only for MS Windows.
  70
  71 GC_NOT_DLL      User-settable macro that overrides _DLL, e.g. if dynamic
  72                 libraries are used, but the collector is in a static library.
  73
  74 __STDC__        Assumed to be defined only by compilers that understand
  75                 prototypes and other C89 features.  Its value is generally
  76                 not used, since we are fine with most nonconforming extensions.
  77
  78 SUNOS5SIGS      Solaris-like signal handling.  This is probably misnamed,
  79                 since it really doesn't guarantee much more than Posix.
  80                 Currently set only for Solaris2.X, HPUX, and DRSNX.  Should
  81                 probably be set for some other platforms.
  82
  83 PCR             Set if the collector is being built as part of the Xerox
  84                 Portable Common Runtime.
  85
  86 USE_COMPILER_TLS  Assume the existence of __thread-style thread-local
  87                 storage.  Set automatically for thread-local allocation with
  88                 the HP/UX vendor compiler.  Usable with gcc on sufficiently
  89                 up-to-date ELF platforms.
  90
  91
  92