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.
  27
  28 The cord test program has not been ported (but should port
  29 easily).  A toy editor (cord/de.exe) based on cords (heavyweight
  30 strings represented as trees) has been ported and is included.
  31 It runs fine under either win32 or win32S.  It serves as an example
  32 of a true Windows application, except that it was written by a
  33 nonexpert Windows programmer.  (There are some peculiarities
  34 in the way files are displayed.  The <cr> is displayed explicitly
  35 for standard DOS text files.  As in the UNIX version, control
  36 characters are displayed explicitly, but in this case as red text.
  37 This may be suboptimal for some tastes and/or sets of default
  38 window colors.)
  39
  40 For Microsoft development tools, rename NT_MAKEFILE as
  41 MAKEFILE.  (Make sure that the CPU environment variable is defined
  42 to be i386.)
  43
  44 For GNU-win32, use the regular makefile, possibly after uncommenting
  45 the line "include Makefile.DLLs".  The latter should be necessary only
  46 if you want to package the collector as a DLL.  The GNU-win32 port is
  47 believed to work only for b18, not b19, probably dues to linker changes
  48 in b19.  This is probably fixable with a different definition of
  49 DATASTART and DATAEND in config.h.
  50
  51 For Borland tools, use BCC_MAKEFILE.  Note that
  52 Borland's compiler defaults to 1 byte alignment in structures (-a1),
  53 whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
  54 The garbage collector in its default configuration EXPECTS AT
  55 LEAST 4 BYTE ALIGNMENT.  Thus the BORLAND DEFAULT MUST
  56 BE OVERRIDDEN.  (In my opinion, it should usually be anyway.
  57 I expect that -a1 introduces major performance penalties on a
  58 486 or Pentium.)  Note that this changes structure layouts.  (As a last
  59 resort, config.h can be changed to allow 1 byte alignment.  But
  60 this has significant negative performance implications.)
  61 The Makefile is set up to assume Borland 4.5.  If you have another
  62 version, change the line near the top.  By default, it does not
  63 require the assembler.  If you do have the assembler, I recommend
  64 removing the -DUSE_GENERIC.
  65
  66 Incremental collection support was recently added.  This is
  67 currently pretty simpleminded.  Pages are protected.  Protection
  68 faults are caught by a handler installed at the bottom of the handler
  69 stack.  This is both slow and interacts poorly with a debugger.
  70 Whenever possible, I recommend adding a call to
  71 GC_enable_incremental at the last possible moment, after most
  72 debugging is complete.  Unlike the UNIX versions, no system
  73 calls are wrapped by the collector itself.  It may be necessary
  74 to wrap ReadFile calls that use a buffer in the heap, so that the
  75 call does not encounter a protection fault while it's running.
  76 (As usual, none of this is an issue unless GC_enable_incremental
  77 is called.)
  78
  79 Note that incremental collection is disabled with -DSMALL_CONFIG,
  80 which is the default for win32.  If you need incremental collection,
  81 undefine SMALL_CONFIG.
  82
  83 Incremental collection is not supported under win32s, and it may not
  84 be possible to do so.  However, win32 applications that attempt to use
  85 incremental collection should continue to run, since the
  86 collector detects if it's running under win32s and turns calls to
  87 GC_enable_incremental() into noops.
  88
  89 James Clark has contributed the necessary code to support win32 threads.
  90 This code is known to exhibit some problems with incremental collection
  91 enabled.  Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE
  92 to build this version.  Note that this requires some files whose names
  93 are more than 8 + 3 characters long.  Thus you should unpack the tar file
  94 so that long file names are preserved.  To build the garbage collector
  95 test with VC++ from the command line, use
  96
  97 nmake /F ".\gc.mak" CFG="gctest - Win32 Release"
  98
  99 This requires that the subdirectory gctest\Release exist.
 100
 101 This version relies on the collector residing in a dll.
 102
 103 This version currently supports incremental collection only if it is
 104 enabled before any additional threads are created.
 105 It is known to not be completely solid.  At a minimum it can deadlock
 106 if a thread starts in the middle of an allocation.  There may be
 107 other problems.  If you need solid support for win32 threads, you
 108 check with Geodesic Systems.  I haven't tried it, but they claim
 109 to support it.
 110
 111 Hans
 112
 113 Ivan V. Demakov's README for the Watcom port:
 114
 115 [ He points out in a later message that there may be a problem compiling
 116   under Windows-3.11 for Windows NT. ]
 117
 118 Watcom C/C++ 10.5, 10.6, 11.0 tested.
 119
 120 The collector runs on WIN32 and DOS4GW dos-extender with both
 121 stack and register based calling conventions (options -5r and -5s).
 122 Incremental collection not supported.
 123
 124 OS/2 not tested, but should work (only some #ifdef's added for OS/2 port).
 125
 126 cord not ported. Watcom C fails to compile it, from first attempt.
 127 Since I don't use it, I don't try to fix it.
 128
 129 cpp_test succeeds, but not compiled automaticaly with WCC_MAKEFILE.
 130
 131
 132 My changes:
 133
 134       * config.h      Added definitions for Watcom C/C++.
 135                       Undefined MPROTECT_VDB for Watcom C/C++ MSWIN32,
 136                       I don't have idea why it not work.
 137
 138       * gc.h          Explicitly declared GC_noop. This prevents
 139                       program crash, compiled with -5r option.
 140
 141       * gc_priv.h     Changed declaration for GC_push_one to make
 142                       compiler happy.
 143                       Added GC_dos4gw_get_mem declaration and
 144                       GET_MEM uses it in DOS4GW environment.
 145
 146       * os_dep.c      Added __WATCOMC__ and DOS4GW #ifdef's.
 147                       Added GC_dos4gw_get_mem.
 148
 149       * mach_dep.c    For Watcom used setjmp method of marking registers.
 150
 151       * WCC_MAKEFILE  New file. Makefile for Watcom C/C++.
 152
 153       * gc_watcom.asm New file. Some functions for DOS4GW.
 154                       This functions may (probably) be done in C,
 155                       but I can't figure out how do this for all
 156                       possible options of compiler.
 157
 158       * README.watcom This file.
 159
 160
 161   Ivan Demakov (email: dem@tgrad.nsk.su)
 162
 163