Mercurial > emacs
comparison gc/doc/README.Mac @ 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 Patrick Beard's Notes for building GC v4.12 with CodeWarrior Pro 2: | |
2 ---------------------------------------------------------------------------- | |
3 The current build environment for the collector is CodeWarrior Pro 2. | |
4 Projects for CodeWarrior Pro 2 (and for quite a few older versions) | |
5 are distributed in the file Mac_projects.sit.hqx. The project file | |
6 :Mac_projects:gc.prj builds static library versions of the collector. | |
7 :Mac_projects:gctest.prj builds the GC test suite. | |
8 | |
9 Configuring the collector is still done by editing the files | |
10 :Mac_files:MacOS_config.h and :Mac_files:MacOS_Test_config.h. | |
11 | |
12 Lars Farm's suggestions on building the collector: | |
13 ---------------------------------------------------------------------------- | |
14 Garbage Collection on MacOS - a manual 'MakeFile' | |
15 ------------------------------------------------- | |
16 | |
17 Project files and IDE's are great on the Macintosh, but they do have | |
18 problems when used as distribution media. This note tries to provide | |
19 porting instructions in pure TEXT form to avoid those problems. A manual | |
20 'makefile' if you like. | |
21 | |
22 GC version: 4.12a2 | |
23 Codewarrior: CWPro1 | |
24 date: 18 July 1997 | |
25 | |
26 The notes may or may not apply to earlier or later versions of the | |
27 GC/CWPro. Actually, they do apply to earlier versions of both except that | |
28 until recently a project could only build one target so each target was a | |
29 separate project. The notes will most likely apply to future versions too. | |
30 Possibly with minor tweaks. | |
31 | |
32 This is just to record my experiences. These notes do not mean I now | |
33 provide a supported port of the GC to MacOS. It works for me. If it works | |
34 for you, great. If it doesn't, sorry, try again...;-) Still, if you find | |
35 errors, please let me know. | |
36 | |
37 mailto: lars.farm@ite.mh.se | |
38 | |
39 address: Lars Farm | |
40 Krönvägen 33b | |
41 856 44 Sundsvall | |
42 Sweden | |
43 | |
44 Porting to MacOS is a bit more complex than it first seems. Which MacOS? | |
45 68K/PowerPC? Which compiler? Each supports both 68K and PowerPC and offer a | |
46 large number of (unique to each environment) compiler settings. Each | |
47 combination of compiler/68K/PPC/settings require a unique combination of | |
48 standard libraries. And the IDE's does not select them for you. They don't | |
49 even check that the library is built with compatible setting and this is | |
50 the major source of problems when porting the GC (and otherwise too). | |
51 | |
52 You will have to make choices when you configure the GC. I've made some | |
53 choices here, but there are other combinations of settings and #defines | |
54 that work too. | |
55 | |
56 As for target settings the major obstacles may be: | |
57 - 68K Processor: check "4-byte Ints". | |
58 - PPC Processor: uncheck "Store Static Data in TOC". | |
59 | |
60 What you need to do: | |
61 =================== | |
62 | |
63 1) Build the GC as a library | |
64 2) Test that the library works with 'test.c'. | |
65 3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'. | |
66 | |
67 1) The Libraries: | |
68 ================= | |
69 I made one project with four targets (68K/PPC tempmem or appheap). One target | |
70 will suffice if you're able to decide which one you want. I wasn't... | |
71 | |
72 Codewarrior allows a large number of compiler/linker settings. I used these: | |
73 | |
74 Settings shared by all targets: | |
75 ------------------------------ | |
76 o Access Paths: | |
77 - User Paths: the GC folder | |
78 - System Paths: {Compiler}:Metrowerks Standard Library: | |
79 {Compiler}:MacOS Support:Headers: | |
80 {Compiler}:MacOS Support:MacHeaders: | |
81 o C/C++ language: | |
82 - inlining: normal | |
83 - direct to SOM: off | |
84 - enable/check: exceptions, RTTI, bool (and if you like pool strings) | |
85 | |
86 PowerPC target settings | |
87 ----------------------- | |
88 o Target Settings: | |
89 - name of target | |
90 - MacOS PPC Linker | |
91 o PPC Target | |
92 - name of library | |
93 o C/C++ language | |
94 - prefix file as described below | |
95 o PPC Processor | |
96 - Struct Alignment: PowerPC | |
97 - uncheck "Store Static Data in TOC" -- important! | |
98 I don't think the others matter, I use full optimization and its ok | |
99 o PPC Linker | |
100 - Factory Settings (SYM file with full paths, faster linking, dead-strip | |
101 static init, Main: __start) | |
102 | |
103 | |
104 68K target settings | |
105 ------------------- | |
106 o Target Settings: | |
107 - name of target | |
108 - MacOS 68K Linker | |
109 o 68K Target | |
110 - name of library | |
111 - A5 relative data | |
112 o C/C++ language | |
113 - prefix file as described below | |
114 o 68K Processor | |
115 - Code model: smart | |
116 - Struct alignment: 68K | |
117 - FP: SANE | |
118 - enable 4-Byte Ints -- important! | |
119 I don't think the others matter. I selected... | |
120 - enable: 68020 | |
121 - enable: global register allocation | |
122 o IR Optimizer | |
123 - enable: Optimize Space, Optimize Speed | |
124 I suppose the others would work too, but haven't tried... | |
125 o 68K Linker | |
126 - Factory Settings (New Style MacsBug,SYM file with full paths, | |
127 A6 Frames, fast link, Merge compiler glue into segment 1, | |
128 dead-strip static init) | |
129 | |
130 Prefix Files to configure the GC sources | |
131 ---------------------------------------- | |
132 The Codewarrior equivalent of commandline compilers -DNAME=X is to use | |
133 prefix-files. A TEXT file that is automatically #included before the first byte | |
134 of every source file. I used these: | |
135 | |
136 ---- ( cut here ) ---- gc_prefix_tempmem.h -- 68K and PPC ----- | |
137 #include "gc_prefix_common.h" | |
138 #undef USE_TEMPORARY_MEMORY | |
139 #define USE_TEMPORARY_MEMORY | |
140 ---- ( cut here ) ---- gc_prefix_appmem.h -- 68K and PPC ----- | |
141 #include "gc_prefix_common.h" | |
142 #undef USE_TEMPORARY_MEMORY | |
143 // #define USE_TEMPORARY_MEMORY | |
144 | |
145 ---- ( cut here ) ---- gc_prefix_common.h -------------------- | |
146 // gc_prefix_common.h | |
147 // ------------------ | |
148 // Codewarrior prefix file to configure the GC libraries | |
149 // | |
150 // prefix files are the Codewarrior equivalent of the | |
151 // command line option -Dname=x frequently seen in makefiles | |
152 | |
153 #if !__MWERKS__ | |
154 #error only tried this with Codewarrior | |
155 #endif | |
156 | |
157 #if macintosh | |
158 #define MSL_USE_PRECOMPILED_HEADERS 0 | |
159 #include <ansi_prefix.mac.h> | |
160 #ifndef __STDC__ | |
161 #define __STDC__ 0 | |
162 #endif | |
163 | |
164 // See list of #defines to configure the library in: 'MakeFile' | |
165 // see also README | |
166 | |
167 #define SILENT // no collection messages. In case | |
168 // of trouble you might want this off | |
169 #define ALL_INTERIOR_POINTERS // follows interior pointers. | |
170 //#define DONT_ADD_BYTE_AT_END // disables the padding if defined. | |
171 //#define SMALL_CONFIG // whether to use a smaller heap. | |
172 #define NO_SIGNALS // signals aren't real on the Macintosh. | |
173 #define ATOMIC_UNCOLLECTABLE // GC_malloc_atomic_uncollectable() | |
174 | |
175 // define either or none as per personal preference | |
176 // used in malloc.c | |
177 #define REDIRECT_MALLOC GC_malloc | |
178 //#define REDIRECT_MALLOC GC_malloc_uncollectable | |
179 // if REDIRECT_MALLOC is #defined make sure that the GC library | |
180 // is listed before the ANSI/ISO libs in the Codewarrior | |
181 // 'Link order' panel | |
182 //#define IGNORE_FREE | |
183 | |
184 // mac specific configs | |
185 //#define USE_TEMPORARY_MEMORY // use Macintosh temporary memory. | |
186 //#define SHARED_LIBRARY_BUILD // build for use in a shared library. | |
187 | |
188 #else | |
189 // could build Win32 here too, or in the future | |
190 // Rhapsody PPC-mach, Rhapsody PPC-MacOS, | |
191 // Rhapsody Intel-mach, Rhapsody Intel-Win32,... | |
192 // ... ugh this will get messy ... | |
193 #endif | |
194 | |
195 // make sure ints are at least 32-bit | |
196 // ( could be set to 16-bit by compiler settings (68K) ) | |
197 | |
198 struct gc_private_assert_intsize_{ char x[ sizeof(int)>=4 ? 1 : 0 ]; }; | |
199 | |
200 #if __powerc | |
201 #if __option(toc_data) | |
202 #error turn off "store static data in TOC" when using GC | |
203 // ... or find a way to add TOC to the root set...(?) | |
204 #endif | |
205 #endif | |
206 ---- ( cut here ) ---- end of gc_prefix_common.h ----------------- | |
207 | |
208 Files to build the GC libraries: | |
209 -------------------------------- | |
210 allchblk.c | |
211 alloc.c | |
212 blacklst.c | |
213 checksums.c | |
214 dbg_mlc.c | |
215 finalize.c | |
216 headers.c | |
217 mach_dep.c | |
218 MacOS.c -- contains MacOS code | |
219 malloc.c | |
220 mallocx.c | |
221 mark.c | |
222 mark_rts.c | |
223 misc.c | |
224 new_hblk.c | |
225 obj_map.c | |
226 os_dep.c -- contains MacOS code | |
227 ptr_chck.c | |
228 reclaim.c | |
229 stubborn.c | |
230 typd_mlc.c | |
231 gc++.cc -- this is 'gc_cpp.cc' with less 'inline' and | |
232 -- throw std::bad_alloc when out of memory | |
233 -- gc_cpp.cc works just fine too | |
234 | |
235 2) Test that the library works with 'test.c'. | |
236 ============================================= | |
237 | |
238 The test app is just an ordinary ANSI-C console app. Make sure settings | |
239 match the library you're testing. | |
240 | |
241 Files | |
242 ----- | |
243 test.c | |
244 the GC library to test -- link order before ANSI libs | |
245 suitable Mac+ANSI libraries | |
246 | |
247 prefix: | |
248 ------ | |
249 ---- ( cut here ) ---- gc_prefix_testlib.h -- all libs ----- | |
250 #define MSL_USE_PRECOMPILED_HEADERS 0 | |
251 #include <ansi_prefix.mac.h> | |
252 #undef NDEBUG | |
253 | |
254 #define ALL_INTERIOR_POINTERS /* for GC_priv.h */ | |
255 ---- ( cut here ) ---- | |
256 | |
257 3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'. | |
258 | |
259 The test app is just an ordinary ANSI-C console app. Make sure settings match | |
260 the library you're testing. | |
261 | |
262 Files | |
263 ----- | |
264 test_cpp.cc | |
265 the GC library to test -- link order before ANSI libs | |
266 suitable Mac+ANSI libraries | |
267 | |
268 prefix: | |
269 ------ | |
270 same as for test.c | |
271 | |
272 For convenience I used one test-project with several targets so that all | |
273 test apps are build at once. Two for each library to test: test.c and | |
274 gc_app.cc. When I was satisfied that the libraries were ok. I put the | |
275 libraries + gc.h + the c++ interface-file in a folder that I then put into | |
276 the MSL hierarchy so that I don't have to alter access-paths in projects | |
277 that use the GC. | |
278 | |
279 After that, just add the proper GC library to your project and the GC is in | |
280 action! malloc will call GC_malloc and free GC_free, new/delete too. You | |
281 don't have to call free or delete. You may have to be a bit cautious about | |
282 delete if you're freeing other resources than RAM. See gc_cpp.h. You can | |
283 also keep coding as always with delete/free. That works too. If you want, | |
284 "include <gc.h> and tweak it's use a bit. | |
285 | |
286 Symantec SPM | |
287 ============ | |
288 It has been a while since I tried the GC in SPM, but I think that the above | |
289 instructions should be sufficient to guide you through in SPM too. SPM | |
290 needs to know where the global data is. Use the files 'datastart.c' and | |
291 'dataend.c'. Put 'datastart.c' at the top of your project and 'dataend.c' | |
292 at the bottom of your project so that all data is surrounded. This is not | |
293 needed in Codewarrior because it provides intrinsic variables | |
294 __datastart__, __data_end__ that wraps all globals. | |
295 | |
296 Source Changes (GC 4.12a2) | |
297 ========================== | |
298 Very few. Just one tiny in the GC, not strictly needed. | |
299 - MacOS.c line 131 in routine GC_MacFreeTemporaryMemory() | |
300 change # if !defined(SHARED_LIBRARY_BUILD) | |
301 to # if !defined(SILENT) && !defined(SHARED_LIBRARY_BUILD) | |
302 To turn off a message when the application quits (actually, I faked | |
303 this change by #defining SHARED_LIBRARY_BUILD in a statically linked | |
304 library for more than a year without ill effects but perhaps this is | |
305 better). | |
306 | |
307 - test_cpp.cc | |
308 made the first lines of main() look like this: | |
309 ------------ | |
310 int main( int argc, char* argv[] ) { | |
311 #endif | |
312 #if macintosh // MacOS | |
313 char* argv_[] = {"test_cpp","10"}; // doesn't | |
314 argv=argv_; // have a | |
315 argc = sizeof(argv_)/sizeof(argv_[0]); // commandline | |
316 #endif // | |
317 | |
318 int i, iters, n; | |
319 # ifndef __GNUC__ | |
320 alloc dummy_to_fool_the_compiler_into_doing_things_it_currently_cant_handle; | |
321 ------------ | |
322 | |
323 - config.h [now gcconfig.h] | |
324 __MWERKS__ does not have to mean MACOS. You can use Codewarrior to | |
325 build a Win32 or BeOS library and soon a Rhapsody library. You may | |
326 have to change that #if... | |
327 | |
328 | |
329 | |
330 It worked for me, hope it works for you. | |
331 | |
332 Lars Farm | |
333 18 July 1997 | |
334 ---------------------------------------------------------------------------- | |
335 | |
336 | |
337 Patrick Beard's instructions (may be dated): | |
338 | |
339 v4.3 of the collector now runs under Symantec C++/THINK C v7.0.4, and | |
340 Metrowerks C/C++ v4.5 both 68K and PowerPC. Project files are provided | |
341 to build and test the collector under both development systems. | |
342 | |
343 Configuration | |
344 ------------- | |
345 | |
346 To configure the collector, under both development systems, a prefix file | |
347 is used to set preprocessor directives. This file is called "MacOS_config.h". | |
348 Also to test the collector, "MacOS_Test_config.h" is provided. | |
349 | |
350 Testing | |
351 ------- | |
352 | |
353 To test the collector (always a good idea), build one of the gctest projects, | |
354 gctest.¹ (Symantec C++/THINK C), mw/gctest.68K.¹, or mw/gctest.PPC.¹. The | |
355 test will ask you how many times to run; 1 should be sufficient. | |
356 | |
357 Building | |
358 -------- | |
359 | |
360 For your convenience project files for the major Macintosh development | |
361 systems are provided. | |
362 | |
363 For Symantec C++/THINK C, you must build the two projects gclib-1.¹ and | |
364 gclib-2.¹. It has to be split up because the collector has more than 32k | |
365 of static data and no library can have more than this in the Symantec | |
366 environment. (Future versions will probably fix this.) | |
367 | |
368 For Metrowerks C/C++ 4.5 you build gc.68K.¹/gc.PPC.¹ and the result will | |
369 be a library called gc.68K.lib/gc.PPC.lib. | |
370 | |
371 Using | |
372 ----- | |
373 | |
374 Under Symantec C++/THINK C, you can just add the gclib-1.¹ and gclib-2.¹ | |
375 projects to your own project. Under Metrowerks, you add gc.68K.lib or | |
376 gc.PPC.lib and two additional files. You add the files called datastart.c | |
377 and dataend.c to your project, bracketing all files that use the collector. | |
378 See mw/gctest.¹ for an example. | |
379 | |
380 Include the projects/libraries you built above into your own project, | |
381 #include "gc.h", and call GC_malloc. You don't have to call GC_free. | |
382 | |
383 | |
384 Patrick C. Beard | |
385 January 4, 1995 |