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 35 [Threads and incremental collection are discussed near the end, below.]
36 37 Microsoft Tools
38 ---------------
39 40 For Microsoft development tools, type
41 "nmake -f NT_MAKEFILE cpu=i386 disable_threads=1 enable_static=1 nodebug=1"
42 to build the release variant of the collector as a static library without
43 threads support.
44 45 In order to use the C++ interface, the client code should include gc_cpp.h
46 and/or gc_allocator.h.
47 48 [See above for gctest.]
49 50 Clients may need to define GC_NOT_DLL before including gc.h, if the
51 collector was built as a static library.
52 53 GNU Tools
54 ---------
55 56 The collector should be buildable under Cygwin with the
57 "./configure; make check" machinery.
58 59 MinGW builds (including for x64) are available both directly (on a Windows
60 host) and via cross-compilation, e.g.
61 "./configure --host=i686-pc-mingw32; make check"
62 63 By default, configure instructs make to build the collector as a DLL (shared
64 library), adding -D GC_DLL to CFLAGS.
65 66 Parallel marker is enabled by default; it could be disabled by
67 "--disable-parallel-mark" option.
68 69 Memory unmapping could be turned off by "--disable-munmap" option.
70 71 Borland Tools
72 -------------
73 74 For Borland tools (e.g. C++Builder), use `cmake -G "Borland Makefiles"`.
75 76 Note that the Borland's compiler defaults to 1-byte alignment in structures
77 (-a1), whereas Visual C++ appears to default to 8-byte alignment.
78 The garbage collector in its default configuration expects at least 4-byte
79 alignment. Thus, the Borland default must be overridden. (In my opinion,
80 it should usually be anyway. I expect that -a1 introduces major performance
81 penalties on a 486 or Pentium.) Note that this changes structure layouts.
82 (As a last resort, -DFORCE_ALIGNMENT_ONE option could be passed to the
83 compiler to allow 1-byte alignment, but this would have significant negative
84 performance implications.)
85 86 Digital Mars compiler
87 ---------------------
88 89 Same as MS Visual C++ but might require
90 -DAO_OLD_STYLE_INTERLOCKED_COMPARE_EXCHANGE option to compile with the
91 parallel marker enabled.
92 93 To build the collector, use the command:
94 make -f digimars.mak
95 96 As usual, specify `check` goal to run the tests:
97 make -f digimars.mak check
98 99 Watcom compiler
100 ---------------
101 102 Ivan V. Demakov's README for the Watcom port:
103 104 The collector has been tested with Watcom C 10.6, 11.0 and OpenWatcom 2.0.
105 It runs under Win32 and win32s, and even under DOS with dos4gw
106 dos-extender. Under Win32 the collector can be built either as dll
107 or as static library.
108 109 Note that all compilations were done under Windows 95, NT, Windows 2K or
110 later. For unknown reason compiling under Windows 3.11 for NT (one
111 attempt has been made) leads to broken executables.
112 113 Incremental collection is supported (except for MSDOS).
114 115 To build the collector, use the command:
116 wmake -f WCC_MAKEFILE
117 118 You might need to customize the build, i.e. set the target platform, library
119 type (dynamic or static), calling conventions, and optimization options.
120 In this case, pass additional arguments to wmake, e.g.:
121 - "ENABLE_STATIC=1" to build the collector as a static library,
122 - "SYSTEM=DOS4GW" to target dos4gw execution environment.
123 124 To run the tests, specify `check` goal:
125 wmake -f WCC_MAKEFILE check
126 127 All programs using libgc should be compiled with 4-byte alignment.
128 For further explanations on this, see comments about Borland compiler.
129 130 If the libgc is compiled as dll, the macro "GC_DLL" should be defined before
131 including "gc.h" (for example, with -DGC_DLL compiler option). It's
132 important, otherwise resulting programs will not run.
133 134 The alternate way to compile the collector is to use cmake build system:
135 cmake -G "Watcom WMake" .
136 cmake --build .
137 138 Special note for OpenWatcom users: the C (unlike the C++) compiler (of the
139 latest stable release, not sure for older ones) doesn't force pointer global
140 variables (i.e. not struct fields, not sure for locals) to be aligned unless
141 optimizing for speed (e.g., "-ot" option is set); the "-zp" option (or align
142 pragma) only controls alignment for structs; I don't know whether it's a bug
143 or a feature, but you are warned.
144 145 Incremental Collection
146 ----------------------
147 148 There is some support for incremental collection. By default, the
149 collector chooses between explicit page protection, and 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 The collector by default handles threads similarly to other platforms.
170 James Clark's code which tracks threads attached to the collector DLL still
171 exists, but requires that both
172 - the collector is built in a DLL with GC_DLL defined, and
173 - GC_use_threads_discovery() is called before the collector initialization,
174 which 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 To build the collector as a dynamic library which handles threads similarly
179 to other platforms, type "nmake -f NT_MAKEFILE". If automatic tracking of
180 threads attached to the collector DLL (i.e. support of both kinds of thread
181 tracking) is needed then delete "-DTHREAD_LOCAL_ALLOC" from NT_MAKEFILE
182 manually before the build.
183 184 The incremental collection is supported only if it is enabled before any
185 additional threads are created.
186 187 Threads are also supported in static library builds with Microsoft tools
188 (e.g., NT_MAKEFILE), as well as with the CMake and GNU tools. The collector
189 must be built with GC_THREADS defined (this is the default in NT_MAKEFILE,
190 CMakeLists.txt and configure).
191 192 For the normal, non-dll-based thread tracking to work properly,
193 threads should be created with GC_CreateThread or GC_beginthreadex,
194 and exit normally, or call GC_endthreadex or GC_ExitThread. (For Cygwin, the
195 standard pthread_create/exit calls could be used instead.) As in the pthread
196 case, including gc.h will redefine CreateThread, _beginthreadex,
197 _endthreadex, and ExitThread to call the GC_ versions instead.
198 199 Note that, as usual, GC_CreateThread tends to introduce resource leaks (in the
200 C runtime) that are avoided by GC_beginthreadex. There is currently no
201 equivalent of _beginthread, and it should not be used.
202 203 GC_INIT() should be called from the main thread before other calls to the
204 collector.
205 206 We strongly advise against using the TerminateThread() Windows API call,
207 especially with the garbage collector. Any use is likely to provoke a
208 crash in the collector, since it makes it impossible for the collector to
209 correctly track threads.
210 211 To build the collector for MinGW pthreads-win32 (or other non-Cygwin pthreads
212 implementation for Windows), use Makefile.direct and explicitly set
213 GC_WIN32_PTHREADS (or pass --enable-threads=pthreads to configure).
214 Use -DPTW32_STATIC_LIB for the static threads library.
215 216 The alternate (better) way to build the library is to use CMake script;
217 please see cmake.md file for the details.
218