toolchain/gcc/boehm-gc/doc/README.win32

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