Annotation of win32/gc/doc/README.win32, revision 1.3
1.3 ! paf 1: The collector has at various times been compiled under Windows 95 & later, NT,
! 2: and XP, with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6, with
! 3: the GNU win32 tools, with Borland 4.5, with Watcom C, and recently
1.1 paf 4: with the Digital Mars compiler. It is likely that some of these have been
5: broken in the meantime. Patches are appreciated.
6:
1.3 ! paf 7: For historical reasons,
! 8: the collector test program "gctest" is linked as a GUI application,
1.1 paf 9: but does not open any windows. Its output appears in the file
10: "gc.log". It may be started from the file manager. The hour glass
11: cursor may appear as long as it's running. If it is started from the
12: command line, it will usually run in the background. Wait a few
13: minutes (a few seconds on a modern machine) before you check the output.
14: You should see either a failure indication or a "Collector appears to
15: work" message.
16:
17: The cord test program has not been ported (but should port
18: easily). A toy editor (cord/de.exe) based on cords (heavyweight
19: strings represented as trees) has been ported and is included.
20: It runs fine under either win32 or win32S. It serves as an example
21: of a true Windows application, except that it was written by a
22: nonexpert Windows programmer. (There are some peculiarities
23: in the way files are displayed. The <cr> is displayed explicitly
24: for standard DOS text files. As in the UNIX version, control
25: characters are displayed explicitly, but in this case as red text.
26: This may be suboptimal for some tastes and/or sets of default
27: window colors.)
28:
29: In general -DREDIRECT_MALLOC is unlikely to work unless the
30: application is completely statically linked.
31:
32: The collector normally allocates memory from the OS with VirtualAlloc.
33: This appears to cause problems under Windows NT and Windows 2000 (but
34: not Windows 95/98) if the memory is later passed to CreateDIBitmap.
35: To work around this problem, build the collector with -DUSE_GLOBAL_ALLOC.
36: This is currently incompatible with -DUSE_MUNMAP. (Thanks to Jonathan
37: Clark for tracking this down. There's some chance this may be fixed
38: in 6.1alpha4, since we now separate heap sections with an unused page.)
39:
1.3 ! paf 40: Microsoft Tools
! 41: ---------------
1.1 paf 42: For Microsoft development tools, rename NT_MAKEFILE as
43: MAKEFILE. (Make sure that the CPU environment variable is defined
44: to be i386.) In order to use the gc_cpp.h C++ interface, all
45: client code should include gc_cpp.h.
46:
1.3 ! paf 47: For historical reasons,
! 48: the collector test program "gctest" is linked as a GUI application,
! 49: but does not open any windows. Its output appears in the file
! 50: "gc.log". It may be started from the file manager. The hour glass
! 51: cursor may appear as long as it's running. If it is started from the
! 52: command line, it will usually run in the background. Wait a few
! 53: minutes (a few seconds on a modern machine) before you check the output.
! 54: You should see either a failure indication or a "Collector appears to
! 55: work" message.
! 56:
1.2 paf 57: If you would prefer a VC++.NET project file, ask boehm@acm.org. One has
58: been contributed, but it seems to contain some absolute paths etc., so
59: it can presumably only be a starting point, and is not in the standard
60: distribution. It is unclear (to me, Hans Boehm) whether it is feasible to
61: change that.
62:
1.1 paf 63: Clients may need to define GC_NOT_DLL before including gc.h, if the
64: collector was built as a static library (as it normally is in the
65: absence of thread support).
66:
1.3 ! paf 67: GNU Tools
! 68: ---------
1.1 paf 69: For GNU-win32, use the regular makefile, possibly after uncommenting
70: the line "include Makefile.DLLs". The latter should be necessary only
1.3 ! paf 71: if you want to package the collector as a DLL.
! 72: [Is the following sentence obsolete? -HB] The GNU-win32 port is
1.1 paf 73: believed to work only for b18, not b19, probably due to linker changes
74: in b19. This is probably fixable with a different definition of
75: DATASTART and DATAEND in gcconfig.h.
76:
1.3 ! paf 77: The collector should also be buildable under Cygwin with either the
! 78: old standard Makefile, or with the "configure;make" machinery.
! 79:
! 80: Borland Tools
! 81: -------------
! 82: [Rarely tested.]
1.1 paf 83: For Borland tools, use BCC_MAKEFILE. Note that
84: Borland's compiler defaults to 1 byte alignment in structures (-a1),
85: whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
86: The garbage collector in its default configuration EXPECTS AT
87: LEAST 4 BYTE ALIGNMENT. Thus the BORLAND DEFAULT MUST
88: BE OVERRIDDEN. (In my opinion, it should usually be anyway.
89: I expect that -a1 introduces major performance penalties on a
90: 486 or Pentium.) Note that this changes structure layouts. (As a last
91: resort, gcconfig.h can be changed to allow 1 byte alignment. But
92: this has significant negative performance implications.)
93: The Makefile is set up to assume Borland 4.5. If you have another
94: version, change the line near the top. By default, it does not
95: require the assembler. If you do have the assembler, I recommend
96: removing the -DUSE_GENERIC.
97:
1.3 ! paf 98: Incremental Collection
! 99: ----------------------
1.1 paf 100: There is some support for incremental collection. This is
101: currently pretty simple-minded. Pages are protected. Protection
102: faults are caught by a handler installed at the bottom of the handler
103: stack. This is both slow and interacts poorly with a debugger.
104: Whenever possible, I recommend adding a call to
105: GC_enable_incremental at the last possible moment, after most
106: debugging is complete. Unlike the UNIX versions, no system
107: calls are wrapped by the collector itself. It may be necessary
108: to wrap ReadFile calls that use a buffer in the heap, so that the
109: call does not encounter a protection fault while it's running.
110: (As usual, none of this is an issue unless GC_enable_incremental
111: is called.)
112:
113: Note that incremental collection is disabled with -DSMALL_CONFIG.
114:
1.3 ! paf 115: Threads
! 116: -------
! 117:
! 118: James Clark has contributed the necessary code to support win32 threads
! 119: with the collector in a DLL.
1.1 paf 120: Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE
121: to build this version. Note that this requires some files whose names
122: are more than 8 + 3 characters long. Thus you should unpack the tar file
123: so that long file names are preserved. To build the garbage collector
124: test with VC++ from the command line, use
125:
126: nmake /F ".\gc.mak" CFG="gctest - Win32 Release"
127:
128: This requires that the subdirectory gctest\Release exist.
129: The test program and DLL will reside in the Release directory.
130:
131: This version relies on the collector residing in a dll.
132:
133: This version currently supports incremental collection only if it is
134: enabled before any additional threads are created.
135:
1.3 ! paf 136: Since 6.3alpha2, threads are also better supported in static library builds
! 137: with Microsoft tools (use NT_STATIC_THREADS_MAKEFILE) and with the GNU
! 138: tools. In all cases,the collector must be built with GC_WIN32_THREADS
! 139: defined, even if the Cygwin pthreads interface is used.
! 140: (NT_STATIC_THREADS_MAKEFILE does this implicitly. Under Cygwin,
! 141: ./configure --enable-threads=posix defines GC_WIN32_THREADS.) Threads must be
! 142: created with GC_CreateThread. This can be accomplished by
! 143: including gc.h and then calling CreateThread, which is redefined
! 144: by gc.h.
! 145:
! 146: For the statically linked versions, it is required that GC_init()
! 147: be called before other GC calls, since there seems to be no implicit way
! 148: to initialize the allocation lock. The easiest way to ensure this in
! 149: portable code is to call GC_INIT() from the main executable (not
! 150: a dynamic library) before calling any other GC_ routines.
! 151:
! 152: We strongly advise against using the TerminateThread() win32 API call,
! 153: especially with the garbage collector. Any use is likely to provoke a
! 154: crash in the GC, since it makes it impossible for the collector to
! 155: correctly track threads.
! 156:
! 157:
! 158: Watcom compiler
! 159: ---------------
1.1 paf 160:
161: Ivan V. Demakov's README for the Watcom port:
162:
163: The collector has been compiled with Watcom C 10.6 and 11.0.
164: It runs under win32, win32s, and even under msdos with dos4gw
165: dos-extender. It should also run under OS/2, though this isn't
166: tested. Under win32 the collector can be built either as dll
167: or as static library.
168:
169: Note that all compilations were done under Windows 95 or NT.
170: For unknown reason compiling under Windows 3.11 for NT (one
171: attempt has been made) leads to broken executables.
172:
173: Incremental collection is not supported.
174:
175: cord is not ported.
176:
177: Before compiling you may need to edit WCC_MAKEFILE to set target
178: platform, library type (dynamic or static), calling conventions, and
179: optimization options.
180:
181: To compile the collector and testing programs use the command:
182: wmake -f WCC_MAKEFILE
183:
184: All programs using gc should be compiled with 4-byte alignment.
185: For further explanations on this see comments about Borland.
186:
1.2 paf 187: If the gc is compiled as dll, the macro ``GC_DLL'' should be defined before
1.1 paf 188: including "gc.h" (for example, with -DGC_DLL compiler option). It's
189: important, otherwise resulting programs will not run.
190:
191: Ivan Demakov (email: ivan@tgrad.nsk.su)
192:
1.3 ! paf 193: Win32S
! 194: ------
! 195:
! 196: [The following is probably obsolete. The win32s support is still in the
! 197: collector, but I doubt anyone cares, or has tested it recently.]
! 198:
! 199: The collector runs under both win32s and win32, but with different semantics.
! 200: Under win32, all writable pages outside of the heaps and stack are
! 201: scanned for roots. Thus the collector sees pointers in DLL data
! 202: segments. Under win32s, only the main data segment is scanned.
! 203: (The main data segment should always be scanned. Under some
! 204: versions of win32s, other regions may also be scanned.)
! 205: Thus all accessible objects should be accessible from local variables
! 206: or variables in the main data segment. Alternatively, other data
! 207: segments (e.g. in DLLs) may be registered with the collector by
! 208: calling GC_init() and then GC_register_root_section(a), where
! 209: a is the address of some variable inside the data segment. (Duplicate
! 210: registrations are ignored, but not terribly quickly.)
! 211:
! 212: (There are two reasons for this. We didn't want to see many 16:16
! 213: pointers. And the VirtualQuery call has different semantics under
! 214: the two systems, and under different versions of win32s.)
1.1 paf 215:
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README.win32 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / gc / doc