1 |
721 |
jeremybenn |
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 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 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 |
|
|
Microsoft Tools
|
41 |
|
|
---------------
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
67 |
|
|
GNU Tools
|
68 |
|
|
---------
|
69 |
|
|
For GNU-win32, use the regular makefile, possibly after uncommenting
|
70 |
|
|
the line "include Makefile.DLLs". The latter should be necessary only
|
71 |
|
|
if you want to package the collector as a DLL.
|
72 |
|
|
[Is the following sentence obsolete? -HB] The GNU-win32 port is
|
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 |
|
|
|
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.]
|
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 |
|
|
|
98 |
|
|
Incremental Collection
|
99 |
|
|
----------------------
|
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 |
|
|
|
115 |
|
|
Threads
|
116 |
|
|
-------
|
117 |
|
|
|
118 |
|
|
James Clark has contributed the necessary code to support win32 threads
|
119 |
|
|
with the collector in a DLL.
|
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 |
|
|
|
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 |
|
|
---------------
|
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 |
|
|
|
187 |
|
|
If the gc is compiled as dll, the macro ``GC_DLL'' should be defined before
|
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 |
|
|
|
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.)
|
215 |
|
|
|