Debian Codegraph @

external/bdwgc/doc/README.win32

raw
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.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 A toy editor (cord/de.exe) based on cords (heavyweight
18 strings represented as trees) has been ported and is included.
19 It runs fine under either win32 or win32S. It serves as an example
20 of a true Windows application, except that it was written by a
21 nonexpert Windows programmer. (There are some peculiarities
22 in the way files are displayed. The <cr> is displayed explicitly
23 for standard DOS text files. As in the UNIX version, control
24 characters are displayed explicitly, but in this case as red text.
25 This may be suboptimal for some tastes and/or sets of default
26 window colors.)
27
28 In general -DREDIRECT_MALLOC is unlikely to work unless the
29 application is completely statically linked.
30
31 The collector normally allocates memory from the OS with VirtualAlloc.
32 This appears to cause problems under Windows NT and Windows 2000 (but
33 not Windows 95/98) if the memory is later passed to CreateDIBitmap.
34 To work around this problem, build the collector with -DUSE_GLOBAL_ALLOC.
35 This is currently incompatible with -DUSE_MUNMAP. (Thanks to Jonathan
36 Clark for tracking this down. There's some chance this may be fixed
37 since we now separate heap sections with an unused page.)
38
39 [Threads and incremental collection are discussed near the end, below.]
40
41 Microsoft Tools
42 ---------------
43 For Microsoft development tools, rename NT_MAKEFILE as
44 MAKEFILE. (Make sure that the CPU environment variable is defined
45 to be i386.) In order to use the gc_cpp.h C++ interface, all
46 client code should include gc_cpp.h.
47
48 [See above for gctest.]
49
50 If you would prefer a VC++ .NET project file, ask Hans Boehm. One has
51 been contributed, but it seems to contain some absolute paths etc., so
52 it can presumably only be a starting point, and is not in the standard
53 distribution. It is unclear (to me, Hans Boehm) whether it is feasible to
54 change that.
55
56 Clients may need to define GC_NOT_DLL before including gc.h, if the
57 collector was built as a static library.
58
59 GNU Tools
60 ---------
61 The collector should be buildable under Cygwin with the
62 "./configure; make check" machinery.
63
64 MinGW builds (including for x86_64) are available both directly (on a Windows
65 host) and via cross-compilation, e.g.
66 "./configure --host=i686-pc-mingw32; make check"
67
68 To build the collector as a DLL, pass "--enable-shared --disable-static" to
69 configure (this will instruct make to compile with -D GC_DLL).
70
71 Parallel marker is enabled by default; it could be disabled by
72 "--disable-parallel-mark" option.
73
74 Memory unmapping could be turned off by "--disable-munmap" option.
75
76 Borland Tools
77 -------------
78 [Rarely tested.]
79 For Borland tools, use BCC_MAKEFILE. Note that
80 Borland's compiler defaults to 1 byte alignment in structures (-a1),
81 whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
82 The garbage collector in its default configuration EXPECTS AT
83 LEAST 4 BYTE ALIGNMENT. Thus the BORLAND DEFAULT MUST
84 BE OVERRIDDEN. (In my opinion, it should usually be anyway.
85 I expect that -a1 introduces major performance penalties on a
86 486 or Pentium.) Note that this changes structure layouts. (As a last
87 resort, gcconfig.h can be changed to allow 1 byte alignment. But
88 this has significant negative performance implications.)
89 The Makefile is set up to assume Borland 4.5. If you have another
90 version, change the line near the top.
91
92 Digital Mars compiler
93 ---------------------
94
95 Same as MS Visual C++ but might require
96 -DAO_OLD_STYLE_INTERLOCKED_COMPARE_EXCHANGE option to compile with the
97 parallel marker enabled.
98
99 Watcom compiler
100 ---------------
101
102 Ivan V. Demakov's README for the Watcom port:
103
104 The collector has been compiled with Watcom C 10.6 and 11.0.
105 It runs under win32, win32s, and even under msdos with dos4gw
106 dos-extender. It should also run under OS/2, though this isn't
107 tested. Under win32 the collector can be built either as dll
108 or as static library.
109
110 Note that all compilations were done under Windows 95 or NT.
111 For unknown reason compiling under Windows 3.11 for NT (one
112 attempt has been made) leads to broken executables.
113
114 Incremental collection is not supported.
115
116 cord is not ported.
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 and testing programs 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
133 Special note for OpenWatcom users: the C (unlike the C++) compiler (of the
134 latest stable release, not sure for older ones) doesn't force pointer global
135 variables (i.e. not struct fields, not sure for locals) to be aligned unless
136 optimizing for speed (e.g., "-ot" option is set); the "-zp" option (or align
137 pragma) only controls alignment for structs; I don't know whether it's a bug or
138 a feature (see an old report of same kind -
139 http://bugzilla.openwatcom.org/show_bug.cgi?id=664), so You are warned.
140
141
142 Incremental Collection
143 ----------------------
144 There is some support for incremental collection. By default, the
145 collector chooses between explicit page protection, and GetWriteWatch-based
146 write tracking automatically, depending on the platform.
147
148 The former is slow and interacts poorly with a debugger.
149 Pages are protected. Protection faults are caught by a handler
150 installed at the bottom of the handler
151 stack. Whenever possible, I recommend adding a call to
152 GC_enable_incremental at the last possible moment, after most
153 debugging is complete. No system
154 calls are wrapped by the collector itself. It may be necessary
155 to wrap ReadFile calls that use a buffer in the heap, so that the
156 call does not encounter a protection fault while it's running.
157 (As usual, none of this is an issue unless GC_enable_incremental
158 is called.)
159
160 Note that incremental collection is disabled with -DSMALL_CONFIG.
161
162 Threads
163 -------
164
165 This version of the collector by default handles threads similarly
166 to other platforms. James Clark's code which tracks threads attached
167 to the collector DLL still exists, but requires that both
168 - the collector is built in a DLL with GC_DLL defined, and
169 - GC_use_threads_discovery() is called before GC initialization, which
170 in turn must happen before creating additional threads.
171 We generally recommend avoiding this if possible, since it seems to
172 be less than 100% reliable.
173
174 Use gc.mak instead of NT_MAKEFILE to build a version that supports
175 both kinds of thread tracking. To build the garbage collector
176 test with VC++ from the command line, use
177
178 nmake /F ".\gc.mak" CFG="gctest - Win32 Release"
179
180 This requires that the subdirectory gctest\Release exist.
181 The test program and DLL will reside in the Release directory.
182
183 This version currently supports incremental collection only if it is
184 enabled before any additional threads are created.
185
186 Since 6.3alpha2, threads are also better supported in static library builds
187 with Microsoft tools (e.g., NT_MAKEFILE) and with the GNU
188 tools. The collector must be built with GC_THREADS defined (this is the
189 default in NT_MAKEFILE, ./configure and CMakeLists.txt).
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() win32 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.