Return to README.win32 CVS log

Up to [local] / OpenXM_contrib2 / asir2000 / gc / doc

Annotation of OpenXM_contrib2/asir2000/gc/doc/README.win32, Revision 1.1

1.1     ! noro        1: The collector has at various times been compiled under Windows 95 & NT,
        !             2: with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6, with
        !             3: the GNU win32 environment, 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: It runs under both win32s and win32, but with different semantics.
        !             8: Under win32, all writable pages outside of the heaps and stack are
        !             9: scanned for roots.  Thus the collector sees pointers in DLL data
        !            10: segments.  Under win32s, only the main data segment is scanned.
        !            11: (The main data segment should always be scanned.  Under some
        !            12: versions of win32s, other regions may also be scanned.)
        !            13: Thus all accessible objects should be accessible from local variables
        !            14: or variables in the main data segment.  Alternatively, other data
        !            15: segments (e.g. in DLLs) may be registered with the collector by
        !            16: calling GC_init() and then GC_register_root_section(a), where
        !            17: a is the address of some variable inside the data segment.  (Duplicate
        !            18: registrations are ignored, but not terribly quickly.)
        !            19:
        !            20: (There are two reasons for this.  We didn't want to see many 16:16
        !            21: pointers.  And the VirtualQuery call has different semantics under
        !            22: the two systems, and under different versions of win32s.)
        !            23:
        !            24: Win32 applications compiled with some flavor of gcc currently behave
        !            25: like win32s applications, in that dynamic library data segments are
        !            26: not scanned.  (Gcc does not directly support Microsoft's "structured
        !            27: exception handling".  It turns out that use of this feature is
        !            28: unavoidable if you scan arbirtray memory segments obtained from
        !            29: VirtualQuery.)
        !            30:
        !            31: The collector test program "gctest" is linked as a GUI application,
        !            32: but does not open any windows.  Its output appears in the file
        !            33: "gc.log".  It may be started from the file manager.  The hour glass
        !            34: cursor may appear as long as it's running.  If it is started from the
        !            35: command line, it will usually run in the background.  Wait a few
        !            36: minutes (a few seconds on a modern machine) before you check the output.
        !            37: You should see either a failure indication or a "Collector appears to
        !            38: work" message.
        !            39:
        !            40: The cord test program has not been ported (but should port
        !            41: easily).  A toy editor (cord/de.exe) based on cords (heavyweight
        !            42: strings represented as trees) has been ported and is included.
        !            43: It runs fine under either win32 or win32S.  It serves as an example
        !            44: of a true Windows application, except that it was written by a
        !            45: nonexpert Windows programmer.  (There are some peculiarities
        !            46: in the way files are displayed.  The <cr> is displayed explicitly
        !            47: for standard DOS text files.  As in the UNIX version, control
        !            48: characters are displayed explicitly, but in this case as red text.
        !            49: This may be suboptimal for some tastes and/or sets of default
        !            50: window colors.)
        !            51:
        !            52: In general -DREDIRECT_MALLOC is unlikely to work unless the
        !            53: application is completely statically linked.
        !            54:
        !            55: The collector normally allocates memory from the OS with VirtualAlloc.
        !            56: This appears to cause problems under Windows NT and Windows 2000 (but
        !            57: not Windows 95/98) if the memory is later passed to CreateDIBitmap.
        !            58: To work around this problem, build the collector with -DUSE_GLOBAL_ALLOC.
        !            59: This is currently incompatible with -DUSE_MUNMAP.  (Thanks to Jonathan
        !            60: Clark for tracking this down.  There's some chance this may be fixed
        !            61: in 6.1alpha4, since we now separate heap sections with an unused page.)
        !            62:
        !            63: For Microsoft development tools, rename NT_MAKEFILE as
        !            64: MAKEFILE.  (Make sure that the CPU environment variable is defined
        !            65: to be i386.)  In order to use the gc_cpp.h C++ interface, all
        !            66: client code should include gc_cpp.h.
        !            67:
        !            68: Clients may need to define GC_NOT_DLL before including gc.h, if the
        !            69: collector was built as a static library (as it normally is in the
        !            70: absence of thread support).
        !            71:
        !            72: For GNU-win32, use the regular makefile, possibly after uncommenting
        !            73: the line "include Makefile.DLLs".  The latter should be necessary only
        !            74: if you want to package the collector as a DLL.  The GNU-win32 port is
        !            75: believed to work only for b18, not b19, probably due to linker changes
        !            76: in b19.  This is probably fixable with a different definition of
        !            77: DATASTART and DATAEND in gcconfig.h.
        !            78:
        !            79: For Borland tools, use BCC_MAKEFILE.  Note that
        !            80: Borland's compiler defaults to 1 byte alignment in structures (-a1),
        !            81: whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
        !            82: The garbage collector in its default configuration EXPECTS AT
        !            83: LEAST 4 BYTE ALIGNMENT.  Thus the BORLAND DEFAULT MUST
        !            84: BE OVERRIDDEN.  (In my opinion, it should usually be anyway.
        !            85: I expect that -a1 introduces major performance penalties on a
        !            86: 486 or Pentium.)  Note that this changes structure layouts.  (As a last
        !            87: resort, gcconfig.h can be changed to allow 1 byte alignment.  But
        !            88: this has significant negative performance implications.)
        !            89: The Makefile is set up to assume Borland 4.5.  If you have another
        !            90: version, change the line near the top.  By default, it does not
        !            91: require the assembler.  If you do have the assembler, I recommend
        !            92: removing the -DUSE_GENERIC.
        !            93:
        !            94: There is some support for incremental collection.  This is
        !            95: currently pretty simple-minded.  Pages are protected.  Protection
        !            96: faults are caught by a handler installed at the bottom of the handler
        !            97: stack.  This is both slow and interacts poorly with a debugger.
        !            98: Whenever possible, I recommend adding a call to
        !            99: GC_enable_incremental at the last possible moment, after most
        !           100: debugging is complete.  Unlike the UNIX versions, no system
        !           101: calls are wrapped by the collector itself.  It may be necessary
        !           102: to wrap ReadFile calls that use a buffer in the heap, so that the
        !           103: call does not encounter a protection fault while it's running.
        !           104: (As usual, none of this is an issue unless GC_enable_incremental
        !           105: is called.)
        !           106:
        !           107: Note that incremental collection is disabled with -DSMALL_CONFIG.
        !           108:
        !           109: James Clark has contributed the necessary code to support win32 threads.
        !           110: Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE
        !           111: to build this version.  Note that this requires some files whose names
        !           112: are more than 8 + 3 characters long.  Thus you should unpack the tar file
        !           113: so that long file names are preserved.  To build the garbage collector
        !           114: test with VC++ from the command line, use
        !           115:
        !           116: nmake /F ".\gc.mak" CFG="gctest - Win32 Release"
        !           117:
        !           118: This requires that the subdirectory gctest\Release exist.
        !           119: The test program and DLL will reside in the Release directory.
        !           120:
        !           121: This version relies on the collector residing in a dll.
        !           122:
        !           123: This version currently supports incremental collection only if it is
        !           124: enabled before any additional threads are created.
        !           125: Version 4.13 attempts to fix some of the earlier problems, but there
        !           126: may be other issues.  If you need solid support for win32 threads, you
        !           127: might check with Geodesic Systems.  Their collector must be licensed,
        !           128: but they have invested far more time in win32-specific issues.
        !           129:
        !           130: Hans
        !           131:
        !           132: Ivan V. Demakov's README for the Watcom port:
        !           133:
        !           134: The collector has been compiled with Watcom C 10.6 and 11.0.
        !           135: It runs under win32, win32s, and even under msdos with dos4gw
        !           136: dos-extender. It should also run under OS/2, though this isn't
        !           137: tested. Under win32 the collector can be built either as dll
        !           138: or as static library.
        !           139:
        !           140: Note that all compilations were done under Windows 95 or NT.
        !           141: For unknown reason compiling under Windows 3.11 for NT (one
        !           142: attempt has been made) leads to broken executables.
        !           143:
        !           144: Incremental collection is not supported.
        !           145:
        !           146: cord is not ported.
        !           147:
        !           148: Before compiling you may need to edit WCC_MAKEFILE to set target
        !           149: platform, library type (dynamic or static), calling conventions, and
        !           150: optimization options.
        !           151:
        !           152: To compile the collector and testing programs use the command:
        !           153:     wmake -f WCC_MAKEFILE
        !           154:
        !           155: All programs using gc should be compiled with 4-byte alignment.
        !           156: For further explanations on this see comments about Borland.
        !           157:
        !           158: If gc compiled as dll, the macro ``GC_DLL'' should be defined before
        !           159: including "gc.h" (for example, with -DGC_DLL compiler option). It's
        !           160: important, otherwise resulting programs will not run.
        !           161:
        !           162: Ivan Demakov (email: ivan@tgrad.nsk.su)
        !           163:
        !           164: