[Emacs-diffs] Changes to emacs/gc/doc/README.win32 [Boehm-versions]

[Dave Love]

Index: emacs/gc/doc/README.win32
diff -c /dev/null emacs/gc/doc/README.win32:1.2.2.1.2.1
*** /dev/null   Mon Jun 16 11:19:57 2003
--- emacs/gc/doc/README.win32   Mon Jun 16 11:19:53 2003
***************
*** 0 ****
--- 1,170 ----
+ The collector has at various times been compiled under Windows 95 & NT,
+ with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6, with
+ the GNU win32 environment, 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.
+ 
+ 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.)
+ 
+ Win32 applications compiled with some flavor of gcc currently behave
+ like win32s applications, in that dynamic library data segments are
+ not scanned.  (Gcc does not directly support Microsoft's "structured
+ exception handling".  It turns out that use of this feature is
+ unavoidable if you scan arbitrary memory segments obtained from
+ VirtualQuery.)
+ 
+ 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 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 <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.)
+ 
+ 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.)
+ 
+ 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.
+ 
+ If you would prefer a VC++.NET project file, ask address@hidden  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).
+ 
+ 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 due 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.
+ 
+ There is some support for incremental collection.  This is
+ currently pretty simple-minded.  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.
+ 
+ James Clark has contributed the necessary code to support win32 threads.
+ 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 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: address@hidden)
+ 
+