Debian Codegraph @

gc/doc/README.Mac

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