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

   1 The collector has at various times been compiled under Windows 95 & later, NT,
   2 and XP, with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6, with
   3 the GNU win32 tools, 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 For historical reasons,
   8 the collector test program "gctest" is linked as a GUI application,
   9 but does not open any windows.  Its output normally appears in the file
  10 "gctest.exe.log".  It may be started from the file manager.  The hour glass
  11 cursor may appear as long as it's running.  If it is started from the
  12 command line, it will usually run in the background.  Wait a few
  13 minutes (a few seconds on a modern machine) before you check the output.
  14 You should see either a failure indication or a "Collector appears to
  15 work" message.
  16
  17 The cord test program has not been ported (but should port
  18 easily).  A toy editor (cord/de.exe) based on cords (heavyweight
  19 strings represented as trees) has been ported and is included.
  20 It runs fine under either win32 or win32S.  It serves as an example
  21 of a true Windows application, except that it was written by a
  22 nonexpert Windows programmer.  (There are some peculiarities
  23 in the way files are displayed.  The <cr> is displayed explicitly
  24 for standard DOS text files.  As in the UNIX version, control
  25 characters are displayed explicitly, but in this case as red text.
  26 This may be suboptimal for some tastes and/or sets of default
  27 window colors.)
  28
  29 In general -DREDIRECT_MALLOC is unlikely to work unless the
  30 application is completely statically linked.
  31
  32 The collector normally allocates memory from the OS with VirtualAlloc.
  33 This appears to cause problems under Windows NT and Windows 2000 (but
  34 not Windows 95/98) if the memory is later passed to CreateDIBitmap.
  35 To work around this problem, build the collector with -DUSE_GLOBAL_ALLOC.
  36 This is currently incompatible with -DUSE_MUNMAP.  (Thanks to Jonathan
  37 Clark for tracking this down.  There's some chance this may be fixed
  38 in 6.1alpha4, since we now separate heap sections with an unused page.)
  39
  40 [Threads and incremental collection are discussed near the end, below.]
  41
  42 Microsoft Tools
  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.)  In order to use the gc_cpp.h C++ interface, all
  47 client code should include gc_cpp.h.
  48
  49 For historical reasons,
  50 the collector test program "gctest" is linked as a GUI application,
  51 but does not open any windows.  Its output appears in the file
  52 "gc.log".  It may be started from the file manager.  The hour glass
  53 cursor may appear as long as it's running.  If it is started from the
  54 command line, it will usually run in the background.  Wait a few
  55 minutes (a few seconds on a modern machine) before you check the output.
  56 You should see either a failure indication or a "Collector appears to
  57 work" message.
  58
  59 If you would prefer a VC++.NET project file, ask boehm@acm.org.  One has
  60 been contributed, but it seems to contain some absolute paths etc., so
  61 it can presumably only be a starting point, and is not in the standard
  62 distribution.  It is unclear (to me, Hans Boehm) whether it is feasible to
  63 change that.
  64
  65 Clients may need to define GC_NOT_DLL before including gc.h, if the
  66 collector was built as a static library (as it normally is in the
  67 absence of thread support).
  68
  69 GNU Tools
  70 ---------
  71 The collector should be buildable under Cygwin with either the old standard
  72 Makefile, or possibly with the "configure --disable-shared;make" machinery.
  73 (For the latter use --enable-threads=posix for thread support.) The major issue
  74 here seems to be that dynamic library support is not currently enabled for
  75 Cygwin.  (This is probably fixable without a great deal of difficulty by
  76 reusing the standard WIN32 code.  But it requires some tweaking.)  As a result
  77 of this, "configure; make; make check" currently does not completely succeed,
  78 though the static library appears to be OK when used only from the main
  79 programs, and correspondingly the Makefile.direct self tests succeed.
  80
  81 Mingw32 builds are not regularly tested, and may or may not work.
  82 The following paragraph is probably obsolete:
  83
  84 For GNU-win32, use the regular makefile, possibly after uncommenting
  85 the line "include Makefile.DLLs".  The latter should be necessary only
  86 if you want to package the collector as a DLL.
  87 [Is the following sentence obsolete? -HB] The GNU-win32 port is
  88 believed to work only for b18, not b19, probably due to linker changes
  89 in b19.  This is probably fixable with a different definition of
  90 DATASTART and DATAEND in gcconfig.h.
  91
  92 Borland Tools
  93 -------------
  94 [Rarely tested.]
  95 For Borland tools, use BCC_MAKEFILE.  Note that
  96 Borland's compiler defaults to 1 byte alignment in structures (-a1),
  97 whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
  98 The garbage collector in its default configuration EXPECTS AT
  99 LEAST 4 BYTE ALIGNMENT.  Thus the BORLAND DEFAULT MUST
 100 BE OVERRIDDEN.  (In my opinion, it should usually be anyway.
 101 I expect that -a1 introduces major performance penalties on a
 102 486 or Pentium.)  Note that this changes structure layouts.  (As a last
 103 resort, gcconfig.h can be changed to allow 1 byte alignment.  But
 104 this has significant negative performance implications.)
 105 The Makefile is set up to assume Borland 4.5.  If you have another
 106 version, change the line near the top.  By default, it does not
 107 require the assembler.  If you do have the assembler, I recommend
 108 removing the -DUSE_GENERIC.
 109
 110
 111 Watcom compiler
 112 ---------------
 113
 114 Ivan V. Demakov's README for the Watcom port:
 115
 116 The collector has been compiled with Watcom C 10.6 and 11.0.
 117 It runs under win32, win32s, and even under msdos with dos4gw
 118 dos-extender. It should also run under OS/2, though this isn't
 119 tested. Under win32 the collector can be built either as dll
 120 or as static library.
 121
 122 Note that all compilations were done under Windows 95 or NT.
 123 For unknown reason compiling under Windows 3.11 for NT (one
 124 attempt has been made) leads to broken executables.
 125
 126 Incremental collection is not supported.
 127
 128 cord is not ported.
 129
 130 Before compiling you may need to edit WCC_MAKEFILE to set target
 131 platform, library type (dynamic or static), calling conventions, and
 132 optimization options.
 133
 134 To compile the collector and testing programs use the command:
 135     wmake -f WCC_MAKEFILE
 136
 137 All programs using gc should be compiled with 4-byte alignment.
 138 For further explanations on this see comments about Borland.
 139
 140 If the gc is compiled as dll, the macro ``GC_DLL'' should be defined before
 141 including "gc.h" (for example, with -DGC_DLL compiler option). It's
 142 important, otherwise resulting programs will not run.
 143
 144 Ivan Demakov (email: ivan@tgrad.nsk.su)
 145
 146 Note from Ivan Maidanski:
 147
 148 Special note for OpenWatcom users: the C (unlike the C++) compiler (of the
 149 latest stable release, not sure for older ones) doesn't force pointer global
 150 variables (i.e. not struct fields, not sure for locals) to be aligned unless
 151 optimizing for speed (eg. "-ot" option is set); the "-zp" option (or align
 152 pragma) only controls alignment for structs; I don't know whether it's a bug or
 153 a feature (see an old report of same kind -
 154 http://bugzilla.openwatcom.org/show_bug.cgi?id=664), so You are warned.
 155
 156
 157 Incremental Collection
 158 ----------------------
 159 There is some support for incremental collection.  By default, the
 160 collector chooses between explicit page protection, anf GetWriteWatch-based
 161 write tracking automatically, depending on the platform.
 162
 163 The former is slow and interacts poorly with a debugger.
 164 Pages are protected.  Protection faults are caught by a handler
 165 installed at the bottom of the handler
 166 stack.  Whenever possible, I recommend adding a call to
 167 GC_enable_incremental at the last possible moment, after most
 168 debugging is complete.  No system
 169 calls are wrapped by the collector itself.  It may be necessary
 170 to wrap ReadFile calls that use a buffer in the heap, so that the
 171 call does not encounter a protection fault while it's running.
 172 (As usual, none of this is an issue unless GC_enable_incremental
 173 is called.)
 174
 175 Note that incremental collection is disabled with -DSMALL_CONFIG.
 176
 177 Threads
 178 -------
 179
 180 This version of the collector by default handles threads similarly
 181 to other platforms.  James Clark's code which tracks threads attached
 182 to the collector DLL still exists, but requires that both
 183 - the collector is built in a DLL with GC_DLL defined, and
 184 - GC_use_DllMain() is called before GC initialization, which
 185   in turn must happen before creating additional threads.
 186 We generally recommend avoiding this if possible, since it seems to
 187 be less than 100% reliable.
 188
 189 Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE
 190 to build a version that supports both kinds of thread tracking.
 191 To build the garbage collector
 192 test with VC++ from the command line, use
 193
 194 nmake /F ".\gc.mak" CFG="gctest - Win32 Release"
 195
 196 This requires that the subdirectory gctest\Release exist.
 197 The test program and DLL will reside in the Release directory.
 198
 199 This version currently supports incremental collection only if it is
 200 enabled before any additional threads are created.
 201
 202 Since 6.3alpha2, threads are also better supported in static library builds
 203 with Microsoft tools (use NT_STATIC_THREADS_MAKEFILE) and with the GNU
 204 tools.  In all cases,the collector must be built with GC_WIN32_THREADS
 205 defined, even if the Cygwin pthreads interface is used.
 206 (NT_STATIC_THREADS_MAKEFILE does this implicitly.  Under Cygwin,
 207 ./configure --enable-threads=posix defines GC_WIN32_THREADS.)
 208
 209 For the normal, non-dll-based thread tracking to work properly,
 210 threads should be created with GC_CreateThread or GC_beginthreadex,
 211 and exit normally or call GC_endthreadex or GC_ExitThread.  (For
 212 Cygwin, use standard pthread calls instead.)  As in the pthread
 213 case, including gc.h will redefine CreateThread, _beginthreadex,
 214 _endthreadex, and ExitThread to call the GC_ versions instead.
 215
 216 Note that, as usual, GC_CreateThread tends to introduce resource leaks
 217 that are avoided by GC_beginthreadex.  There is currently no equivalent of
 218 _beginthread, and it should not be used.
 219
 220 GC_INIT should be called from the main executable before other GC calls.
 221
 222 We strongly advise against using the TerminateThread() win32 API call,
 223 especially with the garbage collector.  Any use is likely to provoke a
 224 crash in the GC, since it makes it impossible for the collector to
 225 correctly track threads.
 226
 227 To build the collector for Mingw32 Pthreads, use Makefile.direct and
 228 explicitly set GC_WIN32_PTHREADS.  Use -DPTW32_STATIC_LIB for the static
 229 threads library.  Note that the DEBUG_WIN32_PTHREADS support in
 230 win32_threads.c is currently broken and looking for someone to debug it.
 231 (This information and the port came from Romano Paolo Tenca).
 232