| 1 |
The collector has at various times been compiled under Windows 95 and later, |
| 2 |
NT, and XP, with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6, |
| 3 |
with the GNU Win32 tools, with Borland C++ Builder, with Watcom C, with EMX, |
| 4 |
and with the Digital Mars compiler (DMC). |
| 5 |
|
| 6 |
For historical reasons, |
| 7 |
the collector test program "gctest" is linked as a GUI application, |
| 8 |
but does not open any windows. Its output normally appears in the file |
| 9 |
"gctest.gc.log". It may be started from the file manager. The hour glass |
| 10 |
cursor may appear as long as it's running. If it is started from the |
| 11 |
command line, it will usually run in the background. Wait a few |
| 12 |
minutes (a few seconds on a modern machine) before you check the output. |
| 13 |
You should see either a failure indication or a "Collector appears to work" |
| 14 |
message. |
| 15 |
|
| 16 |
A toy editor (de.exe) based on cords (heavyweight |
| 17 |
strings represented as trees) has been ported and is included. |
| 18 |
It runs fine under either Win32 or win32s. It serves as an example |
| 19 |
of a true Windows application, except that it was written by a |
| 20 |
nonexpert Windows programmer. (There are some peculiarities |
| 21 |
in the way files are displayed. The <cr> is displayed explicitly |
| 22 |
for standard DOS text files. As in the UNIX version, control |
| 23 |
characters are displayed explicitly, but in this case as red text. |
| 24 |
This may be suboptimal for some tastes and/or sets of default |
| 25 |
window colors.) |
| 26 |
|
| 27 |
In general -DREDIRECT_MALLOC is unlikely to work unless the |
| 28 |
application is completely statically linked. |
| 29 |
|
| 30 |
The collector normally allocates memory from the OS with VirtualAlloc. |
| 31 |
This appears to cause problems under Windows NT and Windows 2000 (but |
| 32 |
not Windows 95/98) if the memory is later passed to CreateDIBitmap. |
| 33 |
To work around this problem, build the collector with -DUSE_GLOBAL_ALLOC. |
| 34 |
This is currently incompatible with -DUSE_MUNMAP. (Thanks to Jonathan |
| 35 |
Clark for tracking this down. There's some chance this may be fixed |
| 36 |
since we now separate heap sections with an unused page.) |
| 37 |
|
| 38 |
[Threads and incremental collection are discussed near the end, below.] |
| 39 |
|
| 40 |
Microsoft Tools |
| 41 |
--------------- |
| 42 |
|
| 43 |
For Microsoft development tools, type |
| 44 |
"nmake -f NT_MAKEFILE cpu=i386 disable_threads=1 enable_static=1 nodebug=1" |
| 45 |
to build the release variant of the collector as a static library without |
| 46 |
threads support. |
| 47 |
|
| 48 |
In order to use the gc_cpp.h C++ interface, all client code should include |
| 49 |
gc_cpp.h. |
| 50 |
|
| 51 |
[See above for gctest.] |
| 52 |
|
| 53 |
If you would prefer a VC++ .NET project file, ask Hans Boehm. One has |
| 54 |
been contributed, but it seems to contain some absolute paths etc., so |
| 55 |
it can presumably only be a starting point, and is not in the standard |
| 56 |
distribution. It is unclear (to me, Hans Boehm) whether it is feasible to |
| 57 |
change that. |
| 58 |
|
| 59 |
Clients may need to define GC_NOT_DLL before including gc.h, if the |
| 60 |
collector was built as a static library. |
| 61 |
|
| 62 |
GNU Tools |
| 63 |
--------- |
| 64 |
|
| 65 |
The collector should be buildable under Cygwin with the |
| 66 |
"./configure; make check" machinery. |
| 67 |
|
| 68 |
MinGW builds (including for x64) are available both directly (on a Windows |
| 69 |
host) and via cross-compilation, e.g. |
| 70 |
"./configure --host=i686-pc-mingw32; make check" |
| 71 |
|
| 72 |
By default, configure instructs make to build the collector as a DLL (shared |
| 73 |
library), adding -D GC_DLL to CFLAGS. |
| 74 |
|
| 75 |
Parallel marker is enabled by default; it could be disabled by |
| 76 |
"--disable-parallel-mark" option. |
| 77 |
|
| 78 |
Memory unmapping could be turned off by "--disable-munmap" option. |
| 79 |
|
| 80 |
Borland Tools |
| 81 |
------------- |
| 82 |
|
| 83 |
For Borland tools, use `cmake -G "Borland Makefiles"`. 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 |
|
| 94 |
Digital Mars compiler |
| 95 |
--------------------- |
| 96 |
|
| 97 |
Same as MS Visual C++ but might require |
| 98 |
-DAO_OLD_STYLE_INTERLOCKED_COMPARE_EXCHANGE option to compile with the |
| 99 |
parallel marker enabled. |
| 100 |
|
| 101 |
Watcom compiler |
| 102 |
--------------- |
| 103 |
|
| 104 |
Ivan V. Demakov's README for the Watcom port: |
| 105 |
|
| 106 |
The collector has been tested with Watcom C 10.6, 11.0 and OpenWatcom 2.0. |
| 107 |
It runs under Win32 and win32s, and even under DOS with dos4gw |
| 108 |
dos-extender. It should also run under OS/2, though this isn't |
| 109 |
tested. Under Win32 the collector can be built either as dll |
| 110 |
or as static library. |
| 111 |
|
| 112 |
Note that all compilations were done under Windows 95 or NT. |
| 113 |
For unknown reason compiling under Windows 3.11 for NT (one |
| 114 |
attempt has been made) leads to broken executables. |
| 115 |
|
| 116 |
Incremental collection is supported (except for MSDOS and OS/2). |
| 117 |
|
| 118 |
Before compiling you may need to edit WCC_MAKEFILE to set target |
| 119 |
platform, library type (dynamic or static), calling conventions, and |
| 120 |
optimization options. |
| 121 |
|
| 122 |
To compile the collector use the command: |
| 123 |
wmake -f WCC_MAKEFILE |
| 124 |
|
| 125 |
All programs using gc should be compiled with 4-byte alignment. |
| 126 |
For further explanations on this see comments about Borland. |
| 127 |
|
| 128 |
If the gc is compiled as dll, the macro "GC_DLL" should be defined before |
| 129 |
including "gc.h" (for example, with -DGC_DLL compiler option). It's |
| 130 |
important, otherwise resulting programs will not run. |
| 131 |
|
| 132 |
The alternate way to compile the collector is to use cmake build system: |
| 133 |
cmake -G "Watcom WMake" . |
| 134 |
cmake --build . |
| 135 |
|
| 136 |
Special note for OpenWatcom users: the C (unlike the C++) compiler (of the |
| 137 |
latest stable release, not sure for older ones) doesn't force pointer global |
| 138 |
variables (i.e. not struct fields, not sure for locals) to be aligned unless |
| 139 |
optimizing for speed (e.g., "-ot" option is set); the "-zp" option (or align |
| 140 |
pragma) only controls alignment for structs; I don't know whether it's a bug or |
| 141 |
a feature (see an old report of same kind - |
| 142 |
http://bugzilla.openwatcom.org/show_bug.cgi?id=664), so You are warned. |
| 143 |
|
| 144 |
Incremental Collection |
| 145 |
---------------------- |
| 146 |
|
| 147 |
There is some support for incremental collection. By default, the |
| 148 |
collector chooses between explicit page protection, and GetWriteWatch-based |
| 149 |
write tracking automatically, depending on the platform. |
| 150 |
|
| 151 |
The former is slow and interacts poorly with a debugger. |
| 152 |
Pages are protected. Protection faults are caught by a handler |
| 153 |
installed at the bottom of the handler |
| 154 |
stack. Whenever possible, I recommend adding a call to |
| 155 |
GC_enable_incremental at the last possible moment, after most |
| 156 |
debugging is complete. No system |
| 157 |
calls are wrapped by the collector itself. It may be necessary |
| 158 |
to wrap ReadFile calls that use a buffer in the heap, so that the |
| 159 |
call does not encounter a protection fault while it's running. |
| 160 |
(As usual, none of this is an issue unless GC_enable_incremental |
| 161 |
is called.) |
| 162 |
|
| 163 |
Note that incremental collection is disabled with -DSMALL_CONFIG. |
| 164 |
|
| 165 |
Threads |
| 166 |
------- |
| 167 |
|
| 168 |
The collector by default handles threads similarly to other platforms. |
| 169 |
James Clark's code which tracks threads attached to the collector DLL still |
| 170 |
exists, but requires that both |
| 171 |
- the collector is built in a DLL with GC_DLL defined, and |
| 172 |
- GC_use_threads_discovery() is called before GC initialization, which |
| 173 |
in turn must happen before creating additional threads. |
| 174 |
We generally recommend avoiding this if possible, since it seems to |
| 175 |
be less than 100% reliable. |
| 176 |
|
| 177 |
To build the collector as a dynamic library which handles threads similarly |
| 178 |
to other platforms, type "nmake -f NT_MAKEFILE". If automatic tracking of |
| 179 |
threads attached to the collector DLL (i.e. support of both kinds of thread |
| 180 |
tracking) is needed then delete "-DTHREAD_LOCAL_ALLOC" from NT_MAKEFILE |
| 181 |
manually before the build. |
| 182 |
|
| 183 |
The incremental collection is supported only if it is enabled before any |
| 184 |
additional threads are created. |
| 185 |
|
| 186 |
Threads are also supported in static library builds with Microsoft tools |
| 187 |
(e.g., NT_MAKEFILE), as well as with the CMake and GNU tools. The collector |
| 188 |
must be built with GC_THREADS defined (this is the default in NT_MAKEFILE, |
| 189 |
CMakeLists.txt and configure). |
| 190 |
|
| 191 |
For the normal, non-dll-based thread tracking to work properly, |
| 192 |
threads should be created with GC_CreateThread or GC_beginthreadex, |
| 193 |
and exit normally, or call GC_endthreadex or GC_ExitThread. (For Cygwin, the |
| 194 |
standard pthread_create/exit calls could be used instead.) As in the pthread |
| 195 |
case, including gc.h will redefine CreateThread, _beginthreadex, |
| 196 |
_endthreadex, and ExitThread to call the GC_ versions instead. |
| 197 |
|
| 198 |
Note that, as usual, GC_CreateThread tends to introduce resource leaks (in the |
| 199 |
C runtime) that are avoided by GC_beginthreadex. There is currently no |
| 200 |
equivalent of _beginthread, and it should not be used. |
| 201 |
|
| 202 |
GC_INIT should be called from the main thread before other GC calls. |
| 203 |
|
| 204 |
We strongly advise against using the TerminateThread() Windows API call, |
| 205 |
especially with the garbage collector. Any use is likely to provoke a |
| 206 |
crash in the GC, since it makes it impossible for the collector to |
| 207 |
correctly track threads. |
| 208 |
|
| 209 |
To build the collector for MinGW pthreads-win32 (or other non-Cygwin pthreads |
| 210 |
implementation for Windows), use Makefile.direct and explicitly set |
| 211 |
GC_WIN32_PTHREADS (or pass --enable-threads=pthreads to configure). |
| 212 |
Use -DPTW32_STATIC_LIB for the static threads library. |
| 213 |
|
| 214 |
The alternate (better) way to build the library is to use CMake script; |
| 215 |
please see README.cmake for the details. |