boehm-gc/README.win32

   1 The collector has only been compiled under Windows NT, with the
   2 original Microsoft SDK, with Visual C++ 2.0 and later, with
   3 the GNU win32 environment, with Borland 4.5, and recently with
   4 Watcom C.
   5
   6 It runs under both win32s and win32, but with different semantics.
   7 Under win32, all writable pages outside of the heaps and stack are
   8 scanned for roots.  Thus the collector sees pointers in DLL data
   9 segments.  Under win32s, only the main data segment is scanned.
  10 (The main data segment should always be scanned.  Under some
  11 versions of win32s, other regions may also be scanned.)
  12 Thus all accessible objects should be accessible from local variables
  13 or variables in the main data segment.  Alternatively, other data
  14 segments (e.g. in DLLs) may be registered with the collector by
  15 calling GC_init() and then GC_register_root_section(a), where
  16 a is the address of some variable inside the data segment.  (Duplicate
  17 registrations are ignored, but not terribly quickly.)
  18
  19 (There are two reasons for this.  We didn't want to see many 16:16
  20 pointers.  And the VirtualQuery call has different semantics under
  21 the two systems, and under different versions of win32s.)
  22
  23 The collector test program "gctest" is linked as a GUI application,
  24 but does not open any windows.  Its output appears in the file
  25 "gc.log".  It may be started from the file manager.  The hour glass
  26 cursor will appear as long as it's running.  If it is started from the
  27 command line, it will usually run in the background.  Wait a few
  28 minutes (a few seconds on a modern machine) before you check the output.
  29 You should see either a failure indication or a "Collector appears to
  30 work" message.
  31
  32 The cord test program has not been ported (but should port
  33 easily).  A toy editor (cord/de.exe) based on cords (heavyweight
  34 strings represented as trees) has been ported and is included.
  35 It runs fine under either win32 or win32S.  It serves as an example
  36 of a true Windows application, except that it was written by a
  37 nonexpert Windows programmer.  (There are some peculiarities
  38 in the way files are displayed.  The <cr> is displayed explicitly
  39 for standard DOS text files.  As in the UNIX version, control
  40 characters are displayed explicitly, but in this case as red text.
  41 This may be suboptimal for some tastes and/or sets of default
  42 window colors.)
  43
  44 For Microsoft development tools, rename NT_MAKEFILE as
  45 MAKEFILE.  (Make sure that the CPU environment variable is defined
  46 to be i386.)
  47
  48 For GNU-win32, use the regular makefile, possibly after uncommenting
  49 the line "include Makefile.DLLs".  The latter should be necessary only
  50 if you want to package the collector as a DLL.  The GNU-win32 port is
  51 believed to work only for b18, not b19, probably dues to linker changes
  52 in b19.  This is probably fixable with a different definition of
  53 DATASTART and DATAEND in gcconfig.h.
  54
  55 For Borland tools, use BCC_MAKEFILE.  Note that
  56 Borland's compiler defaults to 1 byte alignment in structures (-a1),
  57 whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
  58 The garbage collector in its default configuration EXPECTS AT
  59 LEAST 4 BYTE ALIGNMENT.  Thus the BORLAND DEFAULT MUST
  60 BE OVERRIDDEN.  (In my opinion, it should usually be anyway.
  61 I expect that -a1 introduces major performance penalties on a
  62 486 or Pentium.)  Note that this changes structure layouts.  (As a last
  63 resort, gcconfig.h can be changed to allow 1 byte alignment.  But
  64 this has significant negative performance implications.)
  65 The Makefile is set up to assume Borland 4.5.  If you have another
  66 version, change the line near the top.  By default, it does not
  67 require the assembler.  If you do have the assembler, I recommend
  68 removing the -DUSE_GENERIC.
  69
  70 Incremental collection support was recently added.  This is
  71 currently pretty simpleminded.  Pages are protected.  Protection
  72 faults are caught by a handler installed at the bottom of the handler
  73 stack.  This is both slow and interacts poorly with a debugger.
  74 Whenever possible, I recommend adding a call to
  75 GC_enable_incremental at the last possible moment, after most
  76 debugging is complete.  Unlike the UNIX versions, no system
  77 calls are wrapped by the collector itself.  It may be necessary
  78 to wrap ReadFile calls that use a buffer in the heap, so that the
  79 call does not encounter a protection fault while it's running.
  80 (As usual, none of this is an issue unless GC_enable_incremental
  81 is called.)
  82
  83 Note that incremental collection is disabled with -DSMALL_CONFIG,
  84 which is the default for win32.  If you need incremental collection,
  85 undefine SMALL_CONFIG.
  86
  87 Incremental collection is not supported under win32s, and it may not
  88 be possible to do so.  However, win32 applications that attempt to use
  89 incremental collection should continue to run, since the
  90 collector detects if it's running under win32s and turns calls to
  91 GC_enable_incremental() into noops.
  92
  93 James Clark has contributed the necessary code to support win32 threads.
  94 This code is known to exhibit some problems with incremental collection
  95 enabled.  Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE
  96 to build this version.  Note that this requires some files whose names
  97 are more than 8 + 3 characters long.  Thus you should unpack the tar file
  98 so that long file names are preserved.  To build the garbage collector
  99 test with VC++ from the command line, use
 100
 101 nmake /F ".\gc.mak" CFG="gctest - Win32 Release"
 102
 103 This requires that the subdirectory gctest\Release exist.
 104 The test program and DLL will reside in the Release directory.
 105
 106 This version relies on the collector residing in a dll.
 107
 108 This version currently supports incremental collection only if it is
 109 enabled before any additional threads are created.
 110 Version 4.13 attempts to fix some of the earlier problems, but there
 111 may be other issues.  If you need solid support for win32 threads, you
 112 might check with Geodesic Systems.  Their collector must be licensed,
 113 but they have invested far more time in win32-specific issues.
 114
 115 Hans
 116
 117 Ivan V. Demakov's README for the Watcom port:
 118
 119 The collector has been compiled with Watcom C 10.6 and 11.0.
 120 It runs under win32, win32s, and even under msdos with dos4gw
 121 dos-extender. It should also run under OS/2, though this isn't
 122 tested. Under win32 the collector can be built either as dll
 123 or as static library.
 124
 125 Note that all compilations were done under Windows 95 or NT.
 126 For unknown reason compiling under Windows 3.11 for NT (one
 127 attempt has been made) leads to broken executables.
 128
 129 Incremental collection is not supported.
 130
 131 cord is not ported.
 132
 133 Before compiling you may need to edit WCC_MAKEFILE to set target
 134 platform, library type (dynamic or static), calling conventions, and
 135 optimization options.
 136
 137 To compile the collector and testing programs use the command:
 138     wmake -f WCC_MAKEFILE
 139
 140 All programs using gc should be compiled with 4-byte alignment.
 141 For further explanations on this see comments about Borland.
 142
 143 If gc compiled as dll, the macro ``GC_DLL'' should be defined before
 144 including "gc.h" (for example, with -DGC_DLL compiler option). It's
 145 important, otherwise resulting programs will not run.
 146
 147 Ivan Demakov (email: ivan@tgrad.nsk.su)
 148
 149