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