Initial revision

1 files changed, 149 insertions, 0 deletions

diff --git a/gc/README.win32 b/gc/README.win32
new file mode 100644
index 0000000..d78816b
--- /dev/null
+++ b/gc/README.win32
@@ -0,0 +1,149 @@
+The collector has only been compiled under Windows NT, with the
+original Microsoft SDK, with Visual C++ 2.0 and later, with
+the GNU win32 environment, with Borland 4.5, and recently with
+Watcom C.
+
+It runs under both win32s and win32, but with different semantics.
+Under win32, all writable pages outside of the heaps and stack are
+scanned for roots.  Thus the collector sees pointers in DLL data
+segments.  Under win32s, only the main data segment is scanned.
+(The main data segment should always be scanned.  Under some
+versions of win32s, other regions may also be scanned.)
+Thus all accessible objects should be accessible from local variables
+or variables in the main data segment.  Alternatively, other data
+segments (e.g. in DLLs) may be registered with the collector by
+calling GC_init() and then GC_register_root_section(a), where
+a is the address of some variable inside the data segment.  (Duplicate
+registrations are ignored, but not terribly quickly.)
+
+(There are two reasons for this.  We didn't want to see many 16:16
+pointers.  And the VirtualQuery call has different semantics under
+the two systems, and under different versions of win32s.)
+
+The collector test program "gctest" is linked as a GUI application,
+but does not open any windows.  Its output appears in the file
+"gc.log".  It may be started from the file manager.  The hour glass
+cursor will 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 <cr> 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.)
+
+For Microsoft development tools, rename NT_MAKEFILE as
+MAKEFILE.  (Make sure that the CPU environment variable is defined
+to be i386.)
+
+For GNU-win32, use the regular makefile, possibly after uncommenting
+the line "include Makefile.DLLs".  The latter should be necessary only
+if you want to package the collector as a DLL.  The GNU-win32 port is
+believed to work only for b18, not b19, probably dues to linker changes
+in b19.  This is probably fixable with a different definition of
+DATASTART and DATAEND in gcconfig.h.
+
+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.
+
+Incremental collection support was recently added.  This is
+currently pretty simpleminded.  Pages are protected.  Protection
+faults are caught by a handler installed at the bottom of the handler
+stack.  This is both slow and interacts poorly with a debugger.
+Whenever possible, I recommend adding a call to
+GC_enable_incremental at the last possible moment, after most
+debugging is complete.  Unlike the UNIX versions, 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,
+which is the default for win32.  If you need incremental collection,
+undefine SMALL_CONFIG.
+
+Incremental collection is not supported under win32s, and it may not
+be possible to do so.  However, win32 applications that attempt to use
+incremental collection should continue to run, since the
+collector detects if it's running under win32s and turns calls to
+GC_enable_incremental() into noops.
+
+James Clark has contributed the necessary code to support win32 threads.
+This code is known to exhibit some problems with incremental collection
+enabled.  Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE
+to build this version.  Note that this requires some files whose names
+are more than 8 + 3 characters long.  Thus you should unpack the tar file
+so that long file names are preserved.  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 relies on the collector residing in a dll.
+
+This version currently supports incremental collection only if it is
+enabled before any additional threads are created.
+Version 4.13 attempts to fix some of the earlier problems, but there
+may be other issues.  If you need solid support for win32 threads, you
+might check with Geodesic Systems.  Their collector must be licensed,
+but they have invested far more time in win32-specific issues.
+
+Hans
+
+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 gc 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)
+
+