Debian Codegraph @

gc/doc/README.win32

raw
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.