]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | |
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 | For historical reasons, | |
8 | the collector test program "gctest" is linked as a GUI application, | |
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 | |
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 | ||
40 | [Threads and incremental collection are discussed near the end, below.] | |
41 | ||
42 | Microsoft Tools | |
43 | --------------- | |
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 | ||
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 | ||
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 | ||
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 | ||
69 | GNU Tools | |
70 | --------- | |
71 | The collector should be buildable under Cygwin with either the old standard | |
72 | Makefile, or possibly with the "configure --diable-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 | ||
84 | For GNU-win32, use the regular makefile, possibly after uncommenting | |
85 | the line "include Makefile.DLLs". The latter should be necessary only | |
86 | if you want to package the collector as a DLL. | |
87 | [Is the following sentence obsolete? -HB] The GNU-win32 port is | |
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 | ||
92 | Borland Tools | |
93 | ------------- | |
94 | [Rarely tested.] | |
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 | ||
110 | ||
111 | Watcom compiler | |
112 | --------------- | |
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 | ||
140 | If the gc is compiled as dll, the macro ``GC_DLL'' should be defined before | |
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 | ||
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. | |
208 | ||
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. | |
215 | ||
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). | |
221 |