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 platform-specific predefined macros.  This makes
  18 it relatively easy to adapt to new compilers with a different set of
  19 predefined macros.  Currently these macros generally identify platforms
  20 instead of 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 documenting these macros:  (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_NAMESPACE    Tested by gc_cpp.h. Causes gc_cpp symbols to be defined
  34                 in "boehmgc" namespace.
  35
  36 GC_DEBUG_REPLACEMENT    Tested by gc.h. Causes GC_MALLOC/REALLOC() to be
  37                 defined as GC_debug_malloc/realloc_replacement().
  38
  39 GC_NO_THREAD_REDIRECTS  Tested by gc.h.  Prevents redirection of thread
  40                 creation routines etc. to GC_ versions.  Requires the
  41                 programmer to explicitly handle thread registration.
  42
  43 GC_NO_THREAD_DECLS      Tested by gc.h.  MS Windows only.  Do not declare
  44                 Windows thread creation routines and do not include windows.h.
  45
  46 GC_DONT_INCLUDE_WINDOWS_H   Tested by gc.h.  MS Windows only.  Do not include
  47                 windows.h from gc.h (but Windows-specific thread creation
  48                 routines are declared).
  49
  50 GC_UNDERSCORE_STDCALL   Tested by gc.h.  Explicitly prefix exported/imported
  51                 WINAPI (__stdcall) symbols with '_' (underscore).  Could be
  52                 used with MinGW (for x86) compiler (in conjunction with
  53                 GC_DLL) to follow MS conventions for __stdcall symbols naming.
  54
  55 _ENABLE_ARRAYNEW
  56                 #define'd by the Digital Mars C++ compiler when
  57                 operator new[] and delete[] are separately
  58                 overloadable. Used in gc_cpp.h.
  59
  60 _DLL            Tested by gc_config_macros.h. Defined by Visual C++ if runtime
  61                 dynamic libraries are in use.  Used (only if none of GC_DLL,
  62                 GC_NOT_DLL, __GNUC__ are defined) to test whether
  63                 __declspec(dllimport) needs to be added to declarations
  64                 to support the case in which the collector is in a DLL.
  65
  66 GC_DLL          Defined by user if dynamic libraries are being built
  67                 or used.  Also set by gc.h if _DLL is defined (except for
  68                 mingw) while GC_NOT_DLL and __GNUC__ are both undefined.
  69                 This is the macro that is tested internally to determine
  70                 whether the GC is in its own dynamic library.  May need
  71                 to be set by clients before including gc.h.  Note that
  72                 inside the GC implementation it indicates that the
  73                 collector is in its own dynamic library, should export
  74                 its symbols, etc.  But in clients it indicates that the
  75                 GC resides in a different DLL, its entry points should
  76                 be referenced accordingly, and precautions may need to
  77                 be taken to properly deal with statically allocated
  78                 variables in the main program.  Used for MS Windows.
  79                 Also used by GCC v4+ (only when the dynamic shared library
  80                 is being built) to hide internally used symbols.
  81
  82 GC_NOT_DLL      User-settable macro that overrides _DLL, e.g. if runtime
  83                 dynamic libraries are used, but the collector is in a static
  84                 library.  Tested by gc_config_macros.h.
  85
  86
  87 These define arguments influence the collector configuration:
  88
  89 GC_REQUIRE_WCSDUP       Force GC to export GC_wcsdup() (the Unicode version
  90   of GC_strdup); could be useful in the leak-finding mode.  Clients should
  91   define it before including gc.h if the function is needed.
  92
  93 FIND_LEAK       Causes GC_find_leak to be initially set.  This causes the
  94   collector to assume that all inaccessible objects should have been
  95   explicitly deallocated, and reports exceptions.  Finalization and the test
  96   program are not usable in this mode.
  97
  98 GC_FINDLEAK_DELAY_FREE  Turns on deferred freeing of objects in the
  99   leak-finding mode letting the collector to detect alter-object-after-free
 100   errors as well as detect leaked objects sooner (instead of only when program
 101   terminates).  Has no effect if SHORT_DBG_HDRS.
 102
 103 GC_ABORT_ON_LEAK        Causes the application to be terminated once leaked or
 104   smashed (corrupted on use-after-free) objects are found (after printing the
 105   information about that objects).
 106
 107 SUNOS5SIGS      Solaris-like signal handling.  This is probably misnamed,
 108   since it really doesn't guarantee much more than POSIX.  Currently set only
 109   for Solaris2.X, HPUX, and DRSNX.  Should probably be set for some other
 110   platforms.
 111
 112 PCR     Set if the collector is being built as part of the Xerox Portable
 113   Common Runtime.
 114
 115 GC_THREADS      Should set the appropriate one of the below macros,
 116   except GC_WIN32_PTHREADS, which must be set explicitly.  Tested by gc.h.
 117   IMPORTANT: GC_THREADS macro (or the relevant platform-specific deprecated
 118   one) must normally also be defined by the client before including gc.h.
 119   This redefines thread primitives to invoke the GC_ wrappers instead.
 120   Alternatively, linker-based symbol interception can be used on a few
 121   platforms.
 122
 123 GC_SOLARIS_THREADS      Enables support for Solaris pthreads.
 124   Must also define _REENTRANT.  Deprecated, use GC_THREADS instead.
 125
 126 GC_IRIX_THREADS         Enables support for Irix pthreads.  See README.sgi.
 127   Deprecated, use GC_THREADS instead.
 128
 129 GC_HPUX_THREADS         Enables support for HP/UX 11 pthreads.
 130   Also requires _REENTRANT or _POSIX_C_SOURCE=199506L. See README.hp.
 131   Deprecated, use GC_THREADS instead.
 132
 133 GC_LINUX_THREADS        Enables support for Xavier Leroy's Linux threads
 134   or NPTL threads.  See README.linux.  _REENTRANT may also be required.
 135   Deprecated, use GC_THREADS instead.
 136
 137 GC_OSF1_THREADS         Enables support for Tru64 pthreads.  Deprecated, use
 138   GC_THREADS instead.
 139
 140 GC_FREEBSD_THREADS      Enables support for FreeBSD pthreads.  Appeared to run
 141   into some underlying thread problems.  Deprecated, use GC_THREADS instead.
 142
 143 GC_NETBSD_THREADS       Enables support for NetBSD pthreads.  Deprecated, use
 144   GC_THREADS instead.
 145
 146 GC_OPENBSD_THREADS      Enables support for OpenBSD pthreads.  Deprecated,
 147   use GC_THREADS instead.
 148
 149 GC_DARWIN_THREADS       Enables support for Mac OS X pthreads.  Deprecated,
 150   use GC_THREADS instead.
 151
 152 GC_AIX_THREADS  Enables support for IBM AIX threads.  Deprecated, use
 153   GC_THREADS instead.
 154
 155 GC_DGUX386_THREADS      Enables support for DB/UX on I386 threads.
 156   See README.DGUX386.  (Probably has not been tested recently.)  Deprecated,
 157   use GC_THREADS instead.
 158
 159 GC_WIN32_THREADS        Enables support for Win32 threads.  Deprecated,
 160   use GC_THREADS instead.
 161
 162 GC_WIN32_PTHREADS       Enables support for pthreads-win32 (or other
 163   non-Cygwin pthreads library for Windows).  This cannot be enabled
 164   automatically by GC_THREADS, which would assume Win32 native threads.
 165
 166 PTW32_STATIC_LIB        Causes the static version of the Mingw pthreads
 167   library to be used.  Requires GC_WIN32_PTHREADS.
 168
 169 GC_PTHREADS_PARAMARK    Causes pthread-based parallel mark implementation
 170   to be used even if GC_WIN32_PTHREADS is undefined.  (Useful for WinCE.)
 171
 172 ALL_INTERIOR_POINTERS   Allows all pointers to the interior of objects to be
 173   recognized.  (See gc_priv.h for consequences.)  Alternatively,
 174   GC_all_interior_pointers can be set at process initialization time.
 175
 176 SMALL_CONFIG    Tries to tune the collector for small heap sizes,
 177   usually causing it to use less space in such situations.  Incremental
 178   collection no longer works in this case.  Also, removes some
 179   statistic-printing code.  Turns off some optimization algorithms (like data
 180   prefetching in the mark routine).
 181
 182 NO_CLOCK        Do not use system clock.  Disables some statistic printing.
 183
 184 GC_DISABLE_INCREMENTAL  Turn off the incremental collection support.
 185
 186 NO_INCREMENTAL  Causes the GC test programs to not invoke the incremental mode
 187   of the collector.  This has no impact on the generated library, only on the
 188   test programs.  (This is often useful for debugging failures unrelated to
 189   incremental GC.)
 190
 191 LARGE_CONFIG    Tunes the collector for unusually large heaps.
 192   Necessary for heaps larger than about 4 GiB on most (64-bit) machines.
 193   Recommended for heaps larger than about 500 MiB.  Not recommended for
 194   embedded systems.  Could be used in conjunction with SMALL_CONFIG to
 195   generate smaller code (by disabling incremental collection support,
 196   statistic printing and some optimization algorithms).
 197
 198 DONT_ADD_BYTE_AT_END    Meaningful only with ALL_INTERIOR_POINTERS or
 199   GC_all_interior_pointers = 1.  Normally ALL_INTERIOR_POINTERS
 200   causes all objects to be padded so that pointers just past the end of
 201   an object can be recognized.  This can be expensive.  (The padding
 202   is normally more than one byte due to alignment constraints.)
 203   DONT_ADD_BYTE_AT_END disables the padding.
 204
 205 NO_EXECUTE_PERMISSION   May cause some or all of the heap to not
 206   have execute permission, i.e. it may be impossible to execute
 207   code from the heap.  Affects the incremental collector and memory unmapping.
 208   It may greatly improve the performance, since this may avoid some expensive
 209   cache synchronization.  Portable clients should call
 210   GC_set_pages_executable(1) at the process initialization time if the
 211   execute permission is required.
 212
 213 GC_NO_OPERATOR_NEW_ARRAY        Declares that the C++ compiler does not
 214   support the new syntax "operator new[]" for allocating and deleting arrays.
 215   See gc_cpp.h for details.  No effect on the C part of the collector.
 216   This is defined implicitly in a few environments.  Must also be defined
 217   by clients that use gc_cpp.h.
 218
 219 REDIRECT_MALLOC=<X>     Causes malloc to be defined as alias for X.
 220   Unless the following macros are defined, realloc is also redirected
 221   to GC_realloc, and free is redirected to GC_free.
 222   Calloc and str[n]dup are redefined in terms of the new malloc.  X should
 223   be either GC_malloc or GC_malloc_uncollectable, or
 224   GC_debug_malloc_replacement.  (The latter invokes GC_debug_malloc
 225   with dummy source location information, but still results in
 226   properly remembered call stacks on Linux/X86 and Solaris/SPARC.
 227   It requires that the following two macros also be used.)
 228   The former is occasionally useful for working around leaks in code
 229   you don't want to (or can't) look at.  It may not work for
 230   existing code, but it often does.  Neither works on all platforms,
 231   since some ports use malloc or calloc to obtain system memory.
 232   (Probably works for UNIX, and Win32.)  If you build with DBG_HDRS_ALL,
 233   you should only use GC_debug_malloc_replacement as a malloc
 234   replacement.
 235
 236 REDIRECT_REALLOC=<X>    Causes GC_realloc to be redirected to X.
 237   The canonical use is REDIRECT_REALLOC=GC_debug_realloc_replacement,
 238   together with REDIRECT_MALLOC=GC_debug_malloc_replacement to
 239   generate leak reports with call stacks for both malloc and realloc.
 240   This also requires REDIRECT_FREE.
 241
 242 REDIRECT_FREE=<X>       Causes free to be redirected to X.  The canonical use
 243   is REDIRECT_FREE=GC_debug_free.
 244
 245 IGNORE_FREE     Turns calls to free into a no-op.  Only useful with
 246   REDIRECT_MALLOC.
 247
 248 NO_DEBUGGING    Removes GC_dump and the debugging routines it calls.
 249   Reduces code size slightly at the expense of debuggability.
 250
 251 GC_DUMP_REGULARLY       Generate regular debugging dumps.
 252
 253 DEBUG_THREADS   Turn on printing additional thread-support debugging
 254   information.
 255
 256 GC_COLLECT_AT_MALLOC=<n>        Force garbage collection at every
 257   GC_malloc_* call with the size greater than the specified value.
 258   (Might be useful for application debugging or in find-leak mode.)
 259
 260 JAVA_FINALIZATION       Makes it somewhat safer to finalize objects out of
 261   order by specifying a nonstandard finalization mark procedure (see
 262   finalize.c).  Objects reachable from finalizable objects will be marked
 263   in a separate post-pass, and hence their memory won't be reclaimed.
 264   Not recommended unless you are implementing a language that specifies
 265   these semantics.  Actually, the macro determines only the initial value
 266   of GC_java_finalization variable.
 267
 268 FINALIZE_ON_DEMAND      Causes finalizers to be run only in response
 269   to explicit GC_invoke_finalizers() calls.  Actually, the macro only
 270   determines the initial value of GC_finalize_on_demand.
 271
 272 GC_NO_FINALIZATION      Exclude finalization support (for smaller code size).
 273
 274 GC_TOGGLE_REFS_NOT_NEEDED       Exclude toggle-refs support.
 275
 276 GC_ATOMIC_UNCOLLECTABLE Includes code for GC_malloc_atomic_uncollectable.
 277   This is useful if either the vendor malloc implementation is poor,
 278   or if REDIRECT_MALLOC is used.
 279
 280 MARK_BIT_PER_GRANULE    Requests that a mark bit (or often byte)
 281   be allocated for each allocation granule, as opposed to each object.
 282   This often improves speed, possibly at some cost in space and/or
 283   cache footprint.  Normally it is best to let this decision be
 284   made automatically depending on platform.
 285
 286 MARK_BIT_PER_OBJ        Requests that a mark bit be allocated for each
 287   object instead of allocation granule.  The opposite of
 288   MARK_BIT_PER_GRANULE.
 289
 290 HBLKSIZE=<ddd>  Explicitly sets the heap block size (where ddd is a power of
 291   2 between 512 and 16384).  Each heap block is devoted to a single size and
 292   kind of object.  For the incremental collector it makes sense to match
 293   the most likely page size.  Otherwise large values result in more
 294   fragmentation, but generally better performance for large heaps.
 295
 296 USE_MMAP        Use MMAP instead of sbrk to get new memory.
 297   Works for Linux, FreeBSD, Cygwin, Solaris and Irix.
 298
 299 USE_MUNMAP      Causes memory to be returned to the OS under the right
 300   circumstances.  Works under some Unix, Linux and Windows versions.
 301   Requires USE_MMAP except for Windows.
 302
 303 USE_WINALLOC (Cygwin only)   Use Win32 VirtualAlloc (instead of sbrk or mmap)
 304   to get new memory.  Useful if memory unmapping (USE_MUNMAP) is enabled.
 305
 306 MUNMAP_THRESHOLD=<value>        Set the desired memory blocks unmapping
 307   threshold (the number of sequential garbage collections for which
 308   a candidate block for unmapping should remain free).
 309
 310 GC_FORCE_UNMAP_ON_GCOLLECT      Set "unmap as much as possible on explicit GC"
 311   mode on by default.  The mode could be changed at run-time.  Has no effect
 312   unless unmapping is turned on.  Has no effect on implicitly-initiated
 313   garbage collections.
 314
 315 PRINT_BLACK_LIST        Whenever a black list entry is added, i.e. whenever
 316   the garbage collector detects a value that looks almost, but not quite,
 317   like a pointer, print both the address containing the value, and the
 318   value of the near-bogus-pointer.  Can be used to identify regions of
 319   memory that are likely to contribute misidentified pointers.
 320
 321 KEEP_BACK_PTRS  Add code to save back pointers in debugging headers
 322   for objects allocated with the debugging allocator.  If all objects
 323   through GC_MALLOC with GC_DEBUG defined, this allows the client
 324   to determine how particular or randomly chosen objects are reachable
 325   for debugging/profiling purposes.  The gc_backptr.h interface is
 326   implemented only if this is defined.
 327
 328 GC_ASSERTIONS   Enable some internal GC assertion checking.  It is intended
 329   primarily for debugging of the garbage collector itself, but could also
 330   help to identify cases of incorrect GC usage by a client.
 331
 332 DBG_HDRS_ALL    Make sure that all objects have debug headers.  Increases
 333   the reliability (from 99.9999% to 100% mod. bugs) of some of the debugging
 334   code (especially KEEP_BACK_PTRS).  Makes SHORT_DBG_HDRS possible.
 335   Assumes that all client allocation is done through debugging allocators.
 336
 337 SHORT_DBG_HDRS  Assume that all objects have debug headers.  Shorten
 338   the headers to minimize object size, at the expense of checking for
 339   writes past the end of an object.  This is intended for environments
 340   in which most client code is written in a "safe" language, such as
 341   Scheme or Java.  Assumes that all client allocation is done using
 342   the GC_debug_ functions, or through the macros that expand to these,
 343   or by redirecting malloc to GC_debug_malloc_replacement.
 344   (Also eliminates the field for the requested object size.)
 345   Occasionally could be useful for debugging of client code.  Slows down the
 346   collector somewhat, but not drastically.
 347
 348 SAVE_CALL_COUNT=<n>     Set the number of call frames saved with objects
 349   allocated through the debugging interface.  Affects the amount of
 350   information generated in leak reports.  Only matters on platforms
 351   on which we can quickly generate call stacks, currently Linux/X86,
 352   Linux/SPARC, Solaris/SPARC, and platforms that provide execinfo.h.
 353   Default is zero.  On X86, client code should NOT be compiled with
 354   -fomit-frame-pointer.
 355
 356 SAVE_CALL_NARGS=<n>     Set the number of functions arguments to be saved
 357   with each call frame.  Default is zero.  Ignored if we don't know how to
 358   retrieve arguments on the platform.
 359
 360 CHECKSUMS       Reports on erroneously clear dirty bits (at a substantial
 361   performance cost).  Use only for debugging of the incremental collector.
 362   Not compatible with USE_MUNMAP or threads.
 363
 364 GC_GCJ_SUPPORT  Includes support for gcj (and possibly other systems
 365   that include a pointer to a type descriptor in each allocated object).
 366
 367 USE_I686_PREFETCH       Causes the collector to issue Pentium III style
 368   prefetch instructions.  No effect except on Linux/X86 platforms.
 369   Empirically the code appears to still run correctly on Pentium II
 370   processors, though with no performance benefit.  May not run on other
 371   X86 processors probably.  In some cases this improves performance by 15%
 372   or so.
 373
 374 USE_3DNOW_PREFETCH      Causes the collector to issue AMD 3DNow style
 375   prefetch instructions.  Same restrictions as USE_I686_PREFETCH.
 376   Minimally tested.  Didn't appear to be an obvious win on a K6-2/500.
 377
 378 USE_PPC_PREFETCH        Causes the collector to issue PowerPC style
 379   prefetch instructions.  No effect except on PowerPC OS X platforms.
 380   Performance impact untested.
 381
 382 GC_USE_LD_WRAP  In combination with the old flags listed in README.linux
 383   causes the collector some system and pthread calls in a more transparent
 384   fashion than the usual macro-based approach.  Requires GNU ld, and
 385   currently probably works only with Linux.
 386
 387 GC_USE_DLOPEN_WRAP      Causes the collector to redefine malloc and
 388   intercepted pthread routines with their real names, and causes it to use
 389   dlopen and dlsym to refer to the original versions.  This makes it possible
 390   to build an LD_PRELOADable malloc replacement library.
 391
 392 THREAD_LOCAL_ALLOC      Defines GC_malloc(), GC_malloc_atomic() and
 393   GC_gcj_malloc() to use a per-thread set of free-lists. These then allocate
 394   in a way that usually does not involve acquisition of a global lock.
 395   Recommended for multiprocessors.
 396
 397 USE_COMPILER_TLS        Causes thread local allocation to use
 398   the compiler-supported "__thread" thread-local variables.  This is the
 399   default in HP/UX.  It may help performance on recent Linux installations.
 400   (It failed for me on RedHat 8, but appears to work on RedHat 9.)
 401
 402 GC_ATTR_TLS_FAST        Use specific attributes for GC_thread_key like
 403   __attribute__((tls_model("local-exec"))).
 404
 405 PARALLEL_MARK   Allows the marker to run in multiple threads.  Recommended
 406   for multiprocessors.
 407
 408 GC_BUILTIN_ATOMIC       Use C11 (GCC) atomic intrinsics instead of
 409   libatomic_ops primitives.
 410
 411 GC_ALWAYS_MULTITHREADED     Force multi-threaded mode at GC initialization.
 412   (Turns GC_allow_register_threads into a no-op routine.)
 413
 414 GC_ENABLE_SUSPEND_THREAD (Linux only)   Turn on thread suspend/resume API
 415 support.
 416
 417 GC_WINMAIN_REDIRECT (Win32 only)        Redirect (rename) an application
 418   WinMain to GC_WinMain; implement the "real" WinMain which starts a new
 419   thread to call GC_WinMain after initializing the GC.  Useful for WinCE.
 420   Incompatible with GC_DLL.
 421
 422 GC_REGISTER_MEM_PRIVATE (Win32 only)    Force to register MEM_PRIVATE R/W
 423   sections as data roots.  Might be needed for some WinCE 6.0+ custom builds.
 424   (May result in numerous "Data Abort" messages logged to WinCE debugging
 425   console.)  Incompatible with GCC toolchains for WinCE.
 426
 427 NO_GETENV       Prevents the collector from looking at environment variables.
 428   These may otherwise alter its configuration, or turn off GC altogether.
 429   I don't know of a reason to disable this, except possibly if the resulting
 430   process runs as a privileged user.  (This is on by default for WinCE.)
 431
 432 EMPTY_GETENV_RESULTS    Define to workaround a reputed Wine bug in getenv
 433   (getenv() may return an empty string instead of NULL for a missing entry).
 434
 435 GC_READ_ENV_FILE (Win32 only)   Read environment variables from the GC "env"
 436   file (named as the program name plus ".gc.env" extension).  Useful for WinCE
 437   targets (which have no getenv()).  In the file, every variable is specified
 438   in a separate line and the format is as "<name>=<value>" (without spaces).
 439   A comment line may start with any character except for the Latin letters,
 440   the digits and the underscore ('_').  The file encoding is Latin-1.
 441
 442 USE_GLOBAL_ALLOC (Win32 only)   Use GlobalAlloc() instead of VirtualAlloc()
 443   to allocate the heap.  May be needed to work around a Windows NT/2000 issue.
 444   Incompatible with USE_MUNMAP.  See README.win32 for details.
 445
 446 MAKE_BACK_GRAPH         Enable GC_PRINT_BACK_HEIGHT environment variable.
 447   See README.environment for details.  Experimental.  Limited platform
 448   support.  Implies DBG_HDRS_ALL.  All allocation should be done using
 449   the debug interface.
 450
 451 GC_PRINT_BACK_HEIGHT    Permanently turn on back-height printing mode
 452   (useful when NO_GETENV).  See the similar environment variable description
 453   in README.environment.  Requires MAKE_BACK_GRAPH defined.
 454
 455 HANDLE_FORK (Unix and Cygwin only)      Attempt by default to make GC_malloc()
 456   work in a child process fork()'ed from a multi-threaded parent.  Not fully
 457   POSIX-compliant and could be disabled at runtime (before GC_INIT).
 458
 459 TEST_WITH_SYSTEM_MALLOC         Causes gctest to allocate (and leak) large
 460   chunks of memory with the standard system malloc.  This will cause the root
 461   set and collected heap to grow significantly if malloc'ed memory is somehow
 462   getting traced by the collector.  This has no impact on the generated
 463   library; it only affects the test.
 464
 465 POINTER_MASK=<0x...>    Causes candidate pointers to be AND'ed with the given
 466   mask before being considered.  If either this or the following macro is
 467   defined, it will be assumed that all pointers stored in the heap need to be
 468   processed this way.  Stack and register pointers will be considered both
 469   with and without processing.  These macros are normally needed only to
 470   support systems that use high-order pointer tags.  EXPERIMENTAL.
 471
 472 POINTER_SHIFT=<n>       Causes the collector to left shift candidate pointers
 473   by the indicated amount before trying to interpret them.  Applied after
 474   POINTER_MASK. EXPERIMENTAL.  See also the preceding macro.
 475
 476 ENABLE_TRACE    Enables the GC_TRACE=addr environment setting to do its job.
 477   By default this is not supported in order to keep the marker as fast as
 478   possible.
 479
 480 DARWIN_DONT_PARSE_STACK         Causes the Darwin port to discover thread
 481   stack bounds in the same way as other pthread ports, without trying to
 482   walk the frames on the stack.  This is recommended only as a fall-back for
 483   applications that don't support proper stack unwinding.
 484
 485 GC_NO_THREADS_DISCOVERY (Darwin and Win32+DLL only)     Exclude DllMain-based
 486   (on Windows) and task-threads-based (on Darwin) thread registration support.
 487
 488 GC_INSIDE_DLL (Win32 only)      Enable DllMain-based approach of threads
 489   registering even in case GC_DLL is not defined.
 490
 491 GC_DISCOVER_TASK_THREADS (Darwin and Win32+DLL only)    Compile the collector
 492   with the implicitly turned on task-threads-based (on Darwin) or
 493   DllMain-based (on Windows) approach of threads registering.  Only for
 494   compatibility and for the case when it is not possible to call
 495   GC_use_threads_discovery() early (before other GC calls).
 496
 497 USE_PROC_FOR_LIBRARIES  Causes the Linux collector to treat writable
 498   memory mappings (as reported by /proc) as roots, if it doesn't have
 499   other information about them.  It no longer traverses dynamic loader
 500   data structures to find dynamic library static data.  This may be
 501   required for applications that store pointers in mmapped segments without
 502   informing the collector.  But it typically performs poorly, especially
 503   since it will scan inactive but cached NPTL thread stacks completely.
 504
 505 IGNORE_DYNAMIC_LOADING  Don't define DYNAMIC_LOADING even if supported by the
 506   platform (that is, build the collector with disabled tracing of dynamic
 507   library data roots).
 508
 509 NO_PROC_STAT    Causes the collector to avoid relying on Linux
 510   "/proc/self/stat".
 511
 512 NO_GETCONTEXT   Causes the collector to not assume the existence of the
 513   getcontext() function on linux-like platforms.  This currently happens
 514   implicitly on Darwin, Hurd, or ARM or MIPS hardware.  It is explicitly
 515   needed for some old versions of FreeBSD.
 516
 517 STATIC=static   Causes various GC_ symbols that could logically be declared
 518   static to be declared (this is the default if NO_DEBUGGING is specified).
 519   Reduces the number of visible symbols (letting the optimizer do its work
 520   better), which is probably cleaner, but may make some kinds of debugging
 521   and profiling harder.
 522
 523 GC_DLL  Build dynamic-link library (or dynamic shared object).  For Unix this
 524   causes the exported symbols to have 'default' visibility (ignored unless
 525   GCC v4+) and the internal ones to have 'hidden' visibility.
 526
 527 NO_MSGBOX_ON_ERROR (Win32 only)         Do not show Windows message box with
 528   "OK" button on a GC fatal error.  Otherwise the client application is
 529   terminated only once the user clicks "OK" button.  Useful for non-GUI (or
 530   non-interactive) applications.
 531
 532 DONT_USE_USER32_DLL (Win32 only)        Don't use "user32" DLL import library
 533   (containing MessageBox() entry); useful for a static GC library.
 534
 535 GC_PREFER_MPROTECT_VDB  Choose MPROTECT_VDB manually in case of multiple
 536   virtual dirty bit strategies are implemented (at present useful on Win32 and
 537   Solaris to force MPROTECT_VDB strategy instead of the default GWW_VDB or
 538   PROC_VDB ones, respectively).
 539
 540 GC_IGNORE_GCJ_INFO      Disable GCJ-style type information (useful for
 541   debugging on WinCE).
 542
 543 GC_PRINT_VERBOSE_STATS  Permanently turn on verbose logging (useful for
 544   debugging and profiling on WinCE).
 545
 546 GC_ONLY_LOG_TO_FILE     Don't redirect GC stdout and stderr to the log file
 547   specified by GC_LOG_FILE environment variable.  Has effect only when the
 548   variable is set (to anything other than "0").
 549
 550 GC_ANDROID_LOG (Android only)   Output error/debug information to Android log.
 551
 552 GC_DONT_EXPAND  Don't expand the heap unless explicitly requested or forced to.
 553
 554 GC_USE_ENTIRE_HEAP      Causes the non-incremental collector to use the
 555   entire heap before collecting.  This sometimes results in more large block
 556   fragmentation, since very large blocks will tend to get broken up during
 557   each GC cycle.  It is likely to result in a larger working set, but lower
 558   collection frequencies, and hence fewer instructions executed in the
 559   collector.  This macro controls only the default GC_use_entire_heap value.
 560
 561 GC_INITIAL_HEAP_SIZE=<value>    Set the desired default initial heap size
 562   in bytes.
 563
 564 GC_FREE_SPACE_DIVISOR=<value>   Set alternate default GC_free_space_divisor
 565   value.
 566
 567 GC_TIME_LIMIT=<milliseconds>    Set alternate default GC_time_limit value
 568   (setting this to GC_TIME_UNLIMITED will essentially disable incremental
 569   collection while leaving generational collection enabled).
 570
 571 GC_FULL_FREQ=<value>    Set alternate default number of partial collections
 572   between full collections (matters only if incremental collection is on).
 573
 574 NO_CANCEL_SAFE (Posix platforms with threads only)      Don't bother trying
 575   to make the collector safe for thread cancellation; cancellation is not
 576   used.  (Note that if cancellation is used anyway, threads may end up
 577   getting canceled in unexpected places.)  Even without this option,
 578   PTHREAD_CANCEL_ASYNCHRONOUS is never safe with the collector.  (We could
 579   argue about its safety without the collector.)
 580
 581 UNICODE (Win32 only)    Use the Unicode variant ('W') of the Win32 API instead
 582   of ANSI/ASCII one ('A').  Useful for WinCE.
 583
 584 HOST_ANDROID (or __ANDROID__)   Compile for Android NDK platform.
 585
 586 SN_TARGET_PS3           Compile for Sony PS/3.
 587
 588 USE_GET_STACKBASE_FOR_MAIN (Linux only)  Use pthread_attr_getstack() instead
 589   of __libc_stack_end (or instead of any hard-coded value) for getting the
 590   primordial thread stack bottom (useful if the client modifies the program's
 591   address space).