X-Git-Url: http://wien.tomnetworks.com/gitweb/?p=hs-boehmgc.git;a=blobdiff_plain;f=gc-7.2%2Fdoc%2FREADME.win32;fp=gc-7.2%2Fdoc%2FREADME.win32;h=5716d47c01607b46110e2e75a106658dddd5411e;hp=0000000000000000000000000000000000000000;hb=324587ba93dc77f37406d41fd2a20d0e0d94fb1d;hpb=2a4ea609491b225a1ceb06da70396e93916f137a diff --git a/gc-7.2/doc/README.win32 b/gc-7.2/doc/README.win32 new file mode 100644 index 0000000..5716d47 --- /dev/null +++ b/gc-7.2/doc/README.win32 @@ -0,0 +1,227 @@ +The collector has at various times been compiled under Windows 95 & later, NT, +and XP, with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6, with +the GNU win32 tools, with Borland 4.5, with Watcom C, and recently +with the Digital Mars compiler. It is likely that some of these have been +broken in the meantime. Patches are appreciated. + +For historical reasons, +the collector test program "gctest" is linked as a GUI application, +but does not open any windows. Its output normally appears in the file +"gctest.gc.log". It may be started from the file manager. The hour glass +cursor may appear as long as it's running. If it is started from the +command line, it will usually run in the background. Wait a few +minutes (a few seconds on a modern machine) before you check the output. +You should see either a failure indication or a "Collector appears to +work" message. + +The cord test program has not been ported (but should port +easily). A toy editor (cord/de.exe) based on cords (heavyweight +strings represented as trees) has been ported and is included. +It runs fine under either win32 or win32S. It serves as an example +of a true Windows application, except that it was written by a +nonexpert Windows programmer. (There are some peculiarities +in the way files are displayed. The is displayed explicitly +for standard DOS text files. As in the UNIX version, control +characters are displayed explicitly, but in this case as red text. +This may be suboptimal for some tastes and/or sets of default +window colors.) + +In general -DREDIRECT_MALLOC is unlikely to work unless the +application is completely statically linked. + +The collector normally allocates memory from the OS with VirtualAlloc. +This appears to cause problems under Windows NT and Windows 2000 (but +not Windows 95/98) if the memory is later passed to CreateDIBitmap. +To work around this problem, build the collector with -DUSE_GLOBAL_ALLOC. +This is currently incompatible with -DUSE_MUNMAP. (Thanks to Jonathan +Clark for tracking this down. There's some chance this may be fixed +in 6.1alpha4, since we now separate heap sections with an unused page.) + +[Threads and incremental collection are discussed near the end, below.] + +Microsoft Tools +--------------- +For Microsoft development tools, rename NT_MAKEFILE as +MAKEFILE. (Make sure that the CPU environment variable is defined +to be i386.) In order to use the gc_cpp.h C++ interface, all +client code should include gc_cpp.h. + +For historical reasons, +the collector test program "gctest" is linked as a GUI application, +but does not open any windows. Its output appears in the file +"gctest.gc.log". It may be started from the file manager. The hour glass +cursor may appear as long as it's running. If it is started from the +command line, it will usually run in the background. Wait a few +minutes (a few seconds on a modern machine) before you check the output. +You should see either a failure indication or a "Collector appears to +work" message. + +If you would prefer a VC++.NET project file, ask boehm@acm.org. One has +been contributed, but it seems to contain some absolute paths etc., so +it can presumably only be a starting point, and is not in the standard +distribution. It is unclear (to me, Hans Boehm) whether it is feasible to +change that. + +Clients may need to define GC_NOT_DLL before including gc.h, if the +collector was built as a static library (as it normally is in the +absence of thread support). + +GNU Tools +--------- +The collector should be buildable under Cygwin with the +"./configure; make check" machinery. + +MinGW builds (including for x86_64) are available via cross-compilation, e.g. +"./configure --host=i686-pc-mingw32; make check" + +To build the collector as a DLL, pass "--enable-shared --disable-static" to +configure (this will instruct make compile with -D GC_DLL). + +Parallel marker could be enabled via "--enable-parallel-mark". + +Memory unmapping could be enabled via "--enable-munmap" (not well supported +on Cygwin currently). + +Borland Tools +------------- +[Rarely tested.] +For Borland tools, use BCC_MAKEFILE. Note that +Borland's compiler defaults to 1 byte alignment in structures (-a1), +whereas Visual C++ appears to default to 8 byte alignment (/Zp8). +The garbage collector in its default configuration EXPECTS AT +LEAST 4 BYTE ALIGNMENT. Thus the BORLAND DEFAULT MUST +BE OVERRIDDEN. (In my opinion, it should usually be anyway. +I expect that -a1 introduces major performance penalties on a +486 or Pentium.) Note that this changes structure layouts. (As a last +resort, gcconfig.h can be changed to allow 1 byte alignment. But +this has significant negative performance implications.) +The Makefile is set up to assume Borland 4.5. If you have another +version, change the line near the top. By default, it does not +require the assembler. If you do have the assembler, I recommend +removing the -DUSE_GENERIC. + +Digital Mars compiler +--------------------- + +Same as MS Visual C++ but might require +-DAO_OLD_STYLE_INTERLOCKED_COMPARE_EXCHANGE option to compile with the +parallel marker enabled. + +Watcom compiler +--------------- + +Ivan V. Demakov's README for the Watcom port: + +The collector has been compiled with Watcom C 10.6 and 11.0. +It runs under win32, win32s, and even under msdos with dos4gw +dos-extender. It should also run under OS/2, though this isn't +tested. Under win32 the collector can be built either as dll +or as static library. + +Note that all compilations were done under Windows 95 or NT. +For unknown reason compiling under Windows 3.11 for NT (one +attempt has been made) leads to broken executables. + +Incremental collection is not supported. + +cord is not ported. + +Before compiling you may need to edit WCC_MAKEFILE to set target +platform, library type (dynamic or static), calling conventions, and +optimization options. + +To compile the collector and testing programs use the command: + wmake -f WCC_MAKEFILE + +All programs using gc should be compiled with 4-byte alignment. +For further explanations on this see comments about Borland. + +If the gc is compiled as dll, the macro ``GC_DLL'' should be defined before +including "gc.h" (for example, with -DGC_DLL compiler option). It's +important, otherwise resulting programs will not run. + +Ivan Demakov (email: ivan@tgrad.nsk.su) + +Note from Ivan Maidanski: + +Special note for OpenWatcom users: the C (unlike the C++) compiler (of the +latest stable release, not sure for older ones) doesn't force pointer global +variables (i.e. not struct fields, not sure for locals) to be aligned unless +optimizing for speed (eg. "-ot" option is set); the "-zp" option (or align +pragma) only controls alignment for structs; I don't know whether it's a bug or +a feature (see an old report of same kind - +http://bugzilla.openwatcom.org/show_bug.cgi?id=664), so You are warned. + + +Incremental Collection +---------------------- +There is some support for incremental collection. By default, the +collector chooses between explicit page protection, and GetWriteWatch-based +write tracking automatically, depending on the platform. + +The former is slow and interacts poorly with a debugger. +Pages are protected. Protection faults are caught by a handler +installed at the bottom of the handler +stack. Whenever possible, I recommend adding a call to +GC_enable_incremental at the last possible moment, after most +debugging is complete. No system +calls are wrapped by the collector itself. It may be necessary +to wrap ReadFile calls that use a buffer in the heap, so that the +call does not encounter a protection fault while it's running. +(As usual, none of this is an issue unless GC_enable_incremental +is called.) + +Note that incremental collection is disabled with -DSMALL_CONFIG. + +Threads +------- + +This version of the collector by default handles threads similarly +to other platforms. James Clark's code which tracks threads attached +to the collector DLL still exists, but requires that both +- the collector is built in a DLL with GC_DLL defined, and +- GC_use_threads_discovery() is called before GC initialization, which + in turn must happen before creating additional threads. +We generally recommend avoiding this if possible, since it seems to +be less than 100% reliable. + +Use gc.mak (a.k.a NT_THREADS_MAKEFILE) instead of NT_MAKEFILE +to build a version that supports both kinds of thread tracking. +To build the garbage collector +test with VC++ from the command line, use + +nmake /F ".\gc.mak" CFG="gctest - Win32 Release" + +This requires that the subdirectory gctest\Release exist. +The test program and DLL will reside in the Release directory. + +This version currently supports incremental collection only if it is +enabled before any additional threads are created. + +Since 6.3alpha2, threads are also better supported in static library builds +with Microsoft tools (use NT_STATIC_THREADS_MAKEFILE) and with the GNU +tools. The collector must be built with GC_THREADS defined. +(NT_STATIC_THREADS_MAKEFILE does this implicitly. Under Cygwin, +./configure --enable-threads=posix should be used.) + +For the normal, non-dll-based thread tracking to work properly, +threads should be created with GC_CreateThread or GC_beginthreadex, +and exit normally or call GC_endthreadex or GC_ExitThread. (For +Cygwin, use standard pthread calls instead.) As in the pthread +case, including gc.h will redefine CreateThread, _beginthreadex, +_endthreadex, and ExitThread to call the GC_ versions instead. + +Note that, as usual, GC_CreateThread tends to introduce resource leaks +that are avoided by GC_beginthreadex. There is currently no equivalent of +_beginthread, and it should not be used. + +GC_INIT should be called from the main executable before other GC calls. + +We strongly advise against using the TerminateThread() win32 API call, +especially with the garbage collector. Any use is likely to provoke a +crash in the GC, since it makes it impossible for the collector to +correctly track threads. + +To build the collector for Mingw32 Pthreads, use Makefile.direct and +explicitly set GC_WIN32_PTHREADS. Use -DPTW32_STATIC_LIB for the static +threads library.