Daily bump.
[official-gcc.git] / boehm-gc / doc / README.Mac
blob04f468251a1e5f4b94181f9e6ad085b96e8ff442
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.
9 Configuring the collector is still done by editing the files
10 :Mac_files:MacOS_config.h and :Mac_files:MacOS_Test_config.h.
12 Lars Farm's suggestions on building the collector:
13 ----------------------------------------------------------------------------
14 Garbage Collection on MacOS - a manual 'MakeFile'
15 -------------------------------------------------
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.
22     GC version:     4.12a2
23     Codewarrior:    CWPro1
24     date:           18 July 1997
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.
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.
37     mailto:         lars.farm@ite.mh.se
39     address:        Lars Farm
40                     Krönvägen 33b
41                     856 44 Sundsvall
42                     Sweden
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).
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.
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".
60 What you need to do:
61 ===================
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'.
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...
72 Codewarrior allows a large number of compiler/linker settings. I used these:
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)
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)
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)
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:
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
145 ---- ( cut here ) ----  gc_prefix_common.h      --------------------
146 // gc_prefix_common.h
147 // ------------------
148 // Codewarrior prefix file to configure the GC libraries
150 //   prefix files are the Codewarrior equivalent of the
151 //   command line option -Dname=x frequently seen in makefiles
153 #if !__MWERKS__
154   #error only tried this with Codewarrior
155 #endif
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
164   //  See list of #defines to configure the library in: 'MakeFile'
165   //  see also README
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()
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
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.
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
195 // make sure ints are at least 32-bit
196 // ( could be set to 16-bit by compiler settings (68K) )
198 struct gc_private_assert_intsize_{ char x[ sizeof(int)>=4 ? 1 : 0 ]; };
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  -----------------
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
235 2) Test that the library works with 'test.c'.
236 =============================================
238 The test app is just an ordinary ANSI-C console app. Make sure settings
239 match the library you're testing.
241 Files
242 -----
243     test.c
244     the GC library to test        -- link order before ANSI libs
245     suitable Mac+ANSI libraries
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
254 #define ALL_INTERIOR_POINTERS   /* for GC_priv.h */
255 ---- ( cut here ) ----
257 3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'.
259 The test app is just an ordinary ANSI-C console app. Make sure settings match
260 the library you're testing.
262 Files
263 -----
264     test_cpp.cc
265     the GC library to test        -- link order before ANSI libs
266     suitable Mac+ANSI libraries
268 prefix:
269 ------
270 same as for test.c
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.
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.
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.
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).
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                                    //
318   int i, iters, n;
319   # ifndef __GNUC__
320    alloc dummy_to_fool_the_compiler_into_doing_things_it_currently_cant_handle;
321   ------------
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...
330    It worked for me, hope it works for you.
332    Lars Farm
333    18 July 1997
334 ----------------------------------------------------------------------------
337 Patrick Beard's instructions (may be dated):
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.
343 Configuration
344 -------------
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.
350 Testing
351 -------
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.
357 Building 
358 --------
360 For your convenience project files for the major Macintosh development
361 systems are provided.
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.)
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.
371 Using
372 -----
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.
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.
384 Patrick C. Beard
385 January 4, 1995