Mercurial > emacs
comparison gc/doc/README.win32 @ 51488:5de98dce4bd1
*** empty log message ***
author | Dave Love <fx@gnu.org> |
---|---|
date | Thu, 05 Jun 2003 17:49:22 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
51487:01d68b199093 | 51488:5de98dce4bd1 |
---|---|
1 The collector has at various times been compiled under Windows 95 & NT, | |
2 with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6, with | |
3 the GNU win32 environment, 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 It runs under both win32s and win32, but with different semantics. | |
8 Under win32, all writable pages outside of the heaps and stack are | |
9 scanned for roots. Thus the collector sees pointers in DLL data | |
10 segments. Under win32s, only the main data segment is scanned. | |
11 (The main data segment should always be scanned. Under some | |
12 versions of win32s, other regions may also be scanned.) | |
13 Thus all accessible objects should be accessible from local variables | |
14 or variables in the main data segment. Alternatively, other data | |
15 segments (e.g. in DLLs) may be registered with the collector by | |
16 calling GC_init() and then GC_register_root_section(a), where | |
17 a is the address of some variable inside the data segment. (Duplicate | |
18 registrations are ignored, but not terribly quickly.) | |
19 | |
20 (There are two reasons for this. We didn't want to see many 16:16 | |
21 pointers. And the VirtualQuery call has different semantics under | |
22 the two systems, and under different versions of win32s.) | |
23 | |
24 Win32 applications compiled with some flavor of gcc currently behave | |
25 like win32s applications, in that dynamic library data segments are | |
26 not scanned. (Gcc does not directly support Microsoft's "structured | |
27 exception handling". It turns out that use of this feature is | |
28 unavoidable if you scan arbitrary memory segments obtained from | |
29 VirtualQuery.) | |
30 | |
31 The collector test program "gctest" is linked as a GUI application, | |
32 but does not open any windows. Its output appears in the file | |
33 "gc.log". It may be started from the file manager. The hour glass | |
34 cursor may appear as long as it's running. If it is started from the | |
35 command line, it will usually run in the background. Wait a few | |
36 minutes (a few seconds on a modern machine) before you check the output. | |
37 You should see either a failure indication or a "Collector appears to | |
38 work" message. | |
39 | |
40 The cord test program has not been ported (but should port | |
41 easily). A toy editor (cord/de.exe) based on cords (heavyweight | |
42 strings represented as trees) has been ported and is included. | |
43 It runs fine under either win32 or win32S. It serves as an example | |
44 of a true Windows application, except that it was written by a | |
45 nonexpert Windows programmer. (There are some peculiarities | |
46 in the way files are displayed. The <cr> is displayed explicitly | |
47 for standard DOS text files. As in the UNIX version, control | |
48 characters are displayed explicitly, but in this case as red text. | |
49 This may be suboptimal for some tastes and/or sets of default | |
50 window colors.) | |
51 | |
52 In general -DREDIRECT_MALLOC is unlikely to work unless the | |
53 application is completely statically linked. | |
54 | |
55 The collector normally allocates memory from the OS with VirtualAlloc. | |
56 This appears to cause problems under Windows NT and Windows 2000 (but | |
57 not Windows 95/98) if the memory is later passed to CreateDIBitmap. | |
58 To work around this problem, build the collector with -DUSE_GLOBAL_ALLOC. | |
59 This is currently incompatible with -DUSE_MUNMAP. (Thanks to Jonathan | |
60 Clark for tracking this down. There's some chance this may be fixed | |
61 in 6.1alpha4, since we now separate heap sections with an unused page.) | |
62 | |
63 For Microsoft development tools, rename NT_MAKEFILE as | |
64 MAKEFILE. (Make sure that the CPU environment variable is defined | |
65 to be i386.) In order to use the gc_cpp.h C++ interface, all | |
66 client code should include gc_cpp.h. | |
67 | |
68 If you would prefer a VC++.NET project file, ask boehm@acm.org. One has | |
69 been contributed, but it seems to contain some absolute paths etc., so | |
70 it can presumably only be a starting point, and is not in the standard | |
71 distribution. It is unclear (to me, Hans Boehm) whether it is feasible to | |
72 change that. | |
73 | |
74 Clients may need to define GC_NOT_DLL before including gc.h, if the | |
75 collector was built as a static library (as it normally is in the | |
76 absence of thread support). | |
77 | |
78 For GNU-win32, use the regular makefile, possibly after uncommenting | |
79 the line "include Makefile.DLLs". The latter should be necessary only | |
80 if you want to package the collector as a DLL. The GNU-win32 port is | |
81 believed to work only for b18, not b19, probably due to linker changes | |
82 in b19. This is probably fixable with a different definition of | |
83 DATASTART and DATAEND in gcconfig.h. | |
84 | |
85 For Borland tools, use BCC_MAKEFILE. Note that | |
86 Borland's compiler defaults to 1 byte alignment in structures (-a1), | |
87 whereas Visual C++ appears to default to 8 byte alignment (/Zp8). | |
88 The garbage collector in its default configuration EXPECTS AT | |
89 LEAST 4 BYTE ALIGNMENT. Thus the BORLAND DEFAULT MUST | |
90 BE OVERRIDDEN. (In my opinion, it should usually be anyway. | |
91 I expect that -a1 introduces major performance penalties on a | |
92 486 or Pentium.) Note that this changes structure layouts. (As a last | |
93 resort, gcconfig.h can be changed to allow 1 byte alignment. But | |
94 this has significant negative performance implications.) | |
95 The Makefile is set up to assume Borland 4.5. If you have another | |
96 version, change the line near the top. By default, it does not | |
97 require the assembler. If you do have the assembler, I recommend | |
98 removing the -DUSE_GENERIC. | |
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 James Clark has contributed the necessary code to support win32 threads. | |
116 Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE | |
117 to build this version. Note that this requires some files whose names | |
118 are more than 8 + 3 characters long. Thus you should unpack the tar file | |
119 so that long file names are preserved. To build the garbage collector | |
120 test with VC++ from the command line, use | |
121 | |
122 nmake /F ".\gc.mak" CFG="gctest - Win32 Release" | |
123 | |
124 This requires that the subdirectory gctest\Release exist. | |
125 The test program and DLL will reside in the Release directory. | |
126 | |
127 This version relies on the collector residing in a dll. | |
128 | |
129 This version currently supports incremental collection only if it is | |
130 enabled before any additional threads are created. | |
131 Version 4.13 attempts to fix some of the earlier problems, but there | |
132 may be other issues. If you need solid support for win32 threads, you | |
133 might check with Geodesic Systems. Their collector must be licensed, | |
134 but they have invested far more time in win32-specific issues. | |
135 | |
136 Hans | |
137 | |
138 Ivan V. Demakov's README for the Watcom port: | |
139 | |
140 The collector has been compiled with Watcom C 10.6 and 11.0. | |
141 It runs under win32, win32s, and even under msdos with dos4gw | |
142 dos-extender. It should also run under OS/2, though this isn't | |
143 tested. Under win32 the collector can be built either as dll | |
144 or as static library. | |
145 | |
146 Note that all compilations were done under Windows 95 or NT. | |
147 For unknown reason compiling under Windows 3.11 for NT (one | |
148 attempt has been made) leads to broken executables. | |
149 | |
150 Incremental collection is not supported. | |
151 | |
152 cord is not ported. | |
153 | |
154 Before compiling you may need to edit WCC_MAKEFILE to set target | |
155 platform, library type (dynamic or static), calling conventions, and | |
156 optimization options. | |
157 | |
158 To compile the collector and testing programs use the command: | |
159 wmake -f WCC_MAKEFILE | |
160 | |
161 All programs using gc should be compiled with 4-byte alignment. | |
162 For further explanations on this see comments about Borland. | |
163 | |
164 If gc compiled as dll, the macro ``GC_DLL'' should be defined before | |
165 including "gc.h" (for example, with -DGC_DLL compiler option). It's | |
166 important, otherwise resulting programs will not run. | |
167 | |
168 Ivan Demakov (email: ivan@tgrad.nsk.su) | |
169 | |
170 |