Debian Codegraph @

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