Annotation of win32/gc/doc/README.win32, revision 1.4
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.4 ! misha 9: but does not open any windows. Its output normally appears in the file
! 10: "gctest.exe.log". It may be started from the file manager. The hour glass
1.1 paf 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.4 ! misha 40: [Threads and incremental collection are discussed near the end, below.]
! 41:
1.3 paf 42: Microsoft Tools
43: ---------------
1.1 paf 44: For Microsoft development tools, rename NT_MAKEFILE as
45: MAKEFILE. (Make sure that the CPU environment variable is defined
46: to be i386.) In order to use the gc_cpp.h C++ interface, all
47: client code should include gc_cpp.h.
48:
1.3 paf 49: For historical reasons,
50: the collector test program "gctest" is linked as a GUI application,
51: but does not open any windows. Its output appears in the file
52: "gc.log". It may be started from the file manager. The hour glass
53: cursor may appear as long as it's running. If it is started from the
54: command line, it will usually run in the background. Wait a few
55: minutes (a few seconds on a modern machine) before you check the output.
56: You should see either a failure indication or a "Collector appears to
57: work" message.
58:
1.2 paf 59: If you would prefer a VC++.NET project file, ask boehm@acm.org. One has
60: been contributed, but it seems to contain some absolute paths etc., so
61: it can presumably only be a starting point, and is not in the standard
62: distribution. It is unclear (to me, Hans Boehm) whether it is feasible to
63: change that.
64:
1.1 paf 65: Clients may need to define GC_NOT_DLL before including gc.h, if the
66: collector was built as a static library (as it normally is in the
67: absence of thread support).
68:
1.3 paf 69: GNU Tools
70: ---------
1.4 ! misha 71: The collector should be buildable under Cygwin with either the old standard
! 72: Makefile, or possibly with the "configure --disable-shared;make" machinery.
! 73: (For the latter use --enable-threads=posix for thread support.) The major issue
! 74: here seems to be that dynamic library support is not currently enabled for
! 75: Cygwin. (This is probably fixable without a great deal of difficulty by
! 76: reusing the standard WIN32 code. But it requires some tweaking.) As a result
! 77: of this, "configure; make; make check" currently does not completely succeed,
! 78: though the static library appears to be OK when used only from the main
! 79: programs, and correspondingly the Makefile.direct self tests succeed.
! 80:
! 81: Mingw32 builds are not regularly tested, and may or may not work.
! 82: The following paragraph is probably obsolete:
! 83:
1.1 paf 84: For GNU-win32, use the regular makefile, possibly after uncommenting
85: the line "include Makefile.DLLs". The latter should be necessary only
1.3 paf 86: if you want to package the collector as a DLL.
87: [Is the following sentence obsolete? -HB] The GNU-win32 port is
1.1 paf 88: believed to work only for b18, not b19, probably due to linker changes
89: in b19. This is probably fixable with a different definition of
90: DATASTART and DATAEND in gcconfig.h.
91:
1.3 paf 92: Borland Tools
93: -------------
94: [Rarely tested.]
1.1 paf 95: For Borland tools, use BCC_MAKEFILE. Note that
96: Borland's compiler defaults to 1 byte alignment in structures (-a1),
97: whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
98: The garbage collector in its default configuration EXPECTS AT
99: LEAST 4 BYTE ALIGNMENT. Thus the BORLAND DEFAULT MUST
100: BE OVERRIDDEN. (In my opinion, it should usually be anyway.
101: I expect that -a1 introduces major performance penalties on a
102: 486 or Pentium.) Note that this changes structure layouts. (As a last
103: resort, gcconfig.h can be changed to allow 1 byte alignment. But
104: this has significant negative performance implications.)
105: The Makefile is set up to assume Borland 4.5. If you have another
106: version, change the line near the top. By default, it does not
107: require the assembler. If you do have the assembler, I recommend
108: removing the -DUSE_GENERIC.
109:
1.3 paf 110:
111: Watcom compiler
112: ---------------
1.1 paf 113:
114: Ivan V. Demakov's README for the Watcom port:
115:
116: The collector has been compiled with Watcom C 10.6 and 11.0.
117: It runs under win32, win32s, and even under msdos with dos4gw
118: dos-extender. It should also run under OS/2, though this isn't
119: tested. Under win32 the collector can be built either as dll
120: or as static library.
121:
122: Note that all compilations were done under Windows 95 or NT.
123: For unknown reason compiling under Windows 3.11 for NT (one
124: attempt has been made) leads to broken executables.
125:
126: Incremental collection is not supported.
127:
128: cord is not ported.
129:
130: Before compiling you may need to edit WCC_MAKEFILE to set target
131: platform, library type (dynamic or static), calling conventions, and
132: optimization options.
133:
134: To compile the collector and testing programs use the command:
135: wmake -f WCC_MAKEFILE
136:
137: All programs using gc should be compiled with 4-byte alignment.
138: For further explanations on this see comments about Borland.
139:
1.2 paf 140: If the gc is compiled as dll, the macro ``GC_DLL'' should be defined before
1.1 paf 141: including "gc.h" (for example, with -DGC_DLL compiler option). It's
142: important, otherwise resulting programs will not run.
143:
144: Ivan Demakov (email: ivan@tgrad.nsk.su)
145:
1.4 ! misha 146: Incremental Collection
! 147: ----------------------
! 148: There is some support for incremental collection. By default, the
! 149: collector chooses between explicit page protection, anf GetWriteWatch-based
! 150: write tracking automatically, depending on the platform.
! 151:
! 152: The former is slow and interacts poorly with a debugger.
! 153: Pages are protected. Protection faults are caught by a handler
! 154: installed at the bottom of the handler
! 155: stack. Whenever possible, I recommend adding a call to
! 156: GC_enable_incremental at the last possible moment, after most
! 157: debugging is complete. No system
! 158: calls are wrapped by the collector itself. It may be necessary
! 159: to wrap ReadFile calls that use a buffer in the heap, so that the
! 160: call does not encounter a protection fault while it's running.
! 161: (As usual, none of this is an issue unless GC_enable_incremental
! 162: is called.)
! 163:
! 164: Note that incremental collection is disabled with -DSMALL_CONFIG.
! 165:
! 166: Threads
! 167: -------
! 168:
! 169: This version of the collector by default handles threads similarly
! 170: to other platforms. James Clark's code which tracks threads attached
! 171: to the collector DLL still exists, but requires that both
! 172: - the collector is built in a DLL with GC_DLL defined, and
! 173: - GC_use_DllMain() is called before GC initialization, which
! 174: in turn must happen before creating additional threads.
! 175: We generally recommend avoiding this if possible, since it seems to
! 176: be less than 100% reliable.
! 177:
! 178: Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE
! 179: to build a version that supports both kinds of thread tracking.
! 180: To build the garbage collector
! 181: test with VC++ from the command line, use
! 182:
! 183: nmake /F ".\gc.mak" CFG="gctest - Win32 Release"
! 184:
! 185: This requires that the subdirectory gctest\Release exist.
! 186: The test program and DLL will reside in the Release directory.
! 187:
! 188: This version currently supports incremental collection only if it is
! 189: enabled before any additional threads are created.
! 190:
! 191: Since 6.3alpha2, threads are also better supported in static library builds
! 192: with Microsoft tools (use NT_STATIC_THREADS_MAKEFILE) and with the GNU
! 193: tools. In all cases,the collector must be built with GC_WIN32_THREADS
! 194: defined, even if the Cygwin pthreads interface is used.
! 195: (NT_STATIC_THREADS_MAKEFILE does this implicitly. Under Cygwin,
! 196: ./configure --enable-threads=posix defines GC_WIN32_THREADS.)
! 197:
! 198: For the normal, non-dll-based thread tracking to work properly,
! 199: threads should be created with GC_CreateThread or GC_beginthreadex,
! 200: and exit normally or call GC_endthreadex or GC_ExitThread. (For
! 201: Cygwin, use standard pthread calls instead.) As in the pthread
! 202: case, including gc.h will redefine CreateThread, _beginthreadex,
! 203: _endthreadex, and ExitThread to call the GC_ versions instead.
! 204:
! 205: Note that, as usual, GC_CreateThread tends to introduce resource leaks
! 206: that are avoided by GC_beginthreadex. There is currently no equivalent of
! 207: _beginthread, and it should not be used.
1.3 paf 208:
1.4 ! misha 209: GC_INIT should be called from the main executable before other GC calls.
! 210:
! 211: We strongly advise against using the TerminateThread() win32 API call,
! 212: especially with the garbage collector. Any use is likely to provoke a
! 213: crash in the GC, since it makes it impossible for the collector to
! 214: correctly track threads.
1.3 paf 215:
1.4 ! misha 216: To build the collector for Mingw32 Pthreads, use Makefile.direct and
! 217: explicitly set GC_WIN32_PTHREADS. Use -DPTW32_STATIC_LIB for the static
! 218: threads library. Note that the DEBUG_WIN32_PTHREADS support in
! 219: win32_threads.c is currently broken and looking for someone to debug it.
! 220: (This information and the port came from Romano Paolo Tenca).
1.1 paf 221:
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