1 The contents of this file are old and pertain to pre-MacOSX versions.
2 You probably really wanted README.darwin.
4 ---------------------------------------------
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.
14 Configuring the collector is still done by editing the files
15 :Mac_files:MacOS_config.h and :Mac_files:MacOS_Test_config.h.
17 Lars Farm's suggestions on building the collector:
18 ----------------------------------------------------------------------------
19 Garbage Collection on MacOS - a manual 'MakeFile'
20 -------------------------------------------------
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.
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.
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.
42 mailto: lars.farm@ite.mh.se
49 Porting to MacOS is a bit more complex than it first seems. Which MacOS?
50 68K/PowerPC? Which compiler? Each supports both 68K and PowerPC and offer a
51 large number of (unique to each environment) compiler settings. Each
52 combination of compiler/68K/PPC/settings require a unique combination of
53 standard libraries. And the IDE's does not select them for you. They don't
54 even check that the library is built with compatible setting and this is
55 the major source of problems when porting the GC (and otherwise too).
57 You will have to make choices when you configure the GC. I've made some
58 choices here, but there are other combinations of settings and #defines
61 As for target settings the major obstacles may be:
62 - 68K Processor: check "4-byte Ints".
63 - PPC Processor: uncheck "Store Static Data in TOC".
68 1) Build the GC as a library
69 2) Test that the library works with 'test.c'.
70 3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'.
74 I made one project with four targets (68K/PPC tempmem or appheap). One target
75 will suffice if you're able to decide which one you want. I wasn't...
77 Codewarrior allows a large number of compiler/linker settings. I used these:
79 Settings shared by all targets:
80 ------------------------------
82 - User Paths: the GC folder
83 - System Paths: {Compiler}:Metrowerks Standard Library:
84 {Compiler}:MacOS Support:Headers:
85 {Compiler}:MacOS Support:MacHeaders:
89 - enable/check: exceptions, RTTI, bool (and if you like pool strings)
91 PowerPC target settings
92 -----------------------
99 - prefix file as described below
101 - Struct Alignment: PowerPC
102 - uncheck "Store Static Data in TOC" -- important!
103 I don't think the others matter, I use full optimization and its ok
105 - Factory Settings (SYM file with full paths, faster linking, dead-strip
106 static init, Main: __start)
118 - prefix file as described below
121 - Struct alignment: 68K
123 - enable 4-Byte Ints -- important!
124 I don't think the others matter. I selected...
126 - enable: global register allocation
128 - enable: Optimize Space, Optimize Speed
129 I suppose the others would work too, but haven't tried...
131 - Factory Settings (New Style MacsBug,SYM file with full paths,
132 A6 Frames, fast link, Merge compiler glue into segment 1,
133 dead-strip static init)
135 Prefix Files to configure the GC sources
136 ----------------------------------------
137 The Codewarrior equivalent of commandline compilers -DNAME=X is to use
138 prefix-files. A TEXT file that is automatically #included before the first byte
139 of every source file. I used these:
141 ---- ( cut here ) ---- gc_prefix_tempmem.h -- 68K and PPC -----
142 #include "gc_prefix_common.h"
143 #undef USE_TEMPORARY_MEMORY
144 #define USE_TEMPORARY_MEMORY
145 ---- ( cut here ) ---- gc_prefix_appmem.h -- 68K and PPC -----
146 #include "gc_prefix_common.h"
147 #undef USE_TEMPORARY_MEMORY
148 // #define USE_TEMPORARY_MEMORY
150 ---- ( cut here ) ---- gc_prefix_common.h --------------------
151 // gc_prefix_common.h
152 // ------------------
153 // Codewarrior prefix file to configure the GC libraries
155 // prefix files are the Codewarrior equivalent of the
156 // command line option -Dname=x frequently seen in makefiles
159 #error only tried this with Codewarrior
163 #define MSL_USE_PRECOMPILED_HEADERS 0
164 #include <ansi_prefix.mac.h>
169 // See list of #defines to configure the library in: 'MakeFile'
172 #define SILENT // no collection messages. In case
173 // of trouble you might want this off
174 #define ALL_INTERIOR_POINTERS // follows interior pointers.
175 //#define DONT_ADD_BYTE_AT_END // disables the padding if defined.
176 //#define SMALL_CONFIG // whether to use a smaller heap.
177 #define NO_SIGNALS // signals aren't real on the Macintosh.
178 #define ATOMIC_UNCOLLECTABLE // GC_malloc_atomic_uncollectable()
180 // define either or none as per personal preference
182 #define REDIRECT_MALLOC GC_malloc
183 //#define REDIRECT_MALLOC GC_malloc_uncollectable
184 // if REDIRECT_MALLOC is #defined make sure that the GC library
185 // is listed before the ANSI/ISO libs in the Codewarrior
186 // 'Link order' panel
187 //#define IGNORE_FREE
189 // mac specific configs
190 //#define USE_TEMPORARY_MEMORY // use Macintosh temporary memory.
191 //#define SHARED_LIBRARY_BUILD // build for use in a shared library.
194 // could build Win32 here too, or in the future
195 // Rhapsody PPC-mach, Rhapsody PPC-MacOS,
196 // Rhapsody Intel-mach, Rhapsody Intel-Win32,...
197 // ... ugh this will get messy ...
200 // make sure ints are at least 32-bit
201 // ( could be set to 16-bit by compiler settings (68K) )
203 struct gc_private_assert_intsize_{ char x[ sizeof(int)>=4 ? 1 : 0 ]; };
206 #if __option(toc_data)
207 #error turn off "store static data in TOC" when using GC
208 // ... or find a way to add TOC to the root set...(?)
211 ---- ( cut here ) ---- end of gc_prefix_common.h -----------------
213 Files to build the GC libraries:
214 --------------------------------
223 MacOS.c -- contains MacOS code
231 os_dep.c -- contains MacOS code
236 gc++.cc -- this is 'gc_cpp.cc' with less 'inline' and
237 -- throw std::bad_alloc when out of memory
238 -- gc_cpp.cc works just fine too
240 2) Test that the library works with 'test.c'.
241 =============================================
243 The test app is just an ordinary ANSI-C console app. Make sure settings
244 match the library you're testing.
249 the GC library to test -- link order before ANSI libs
250 suitable Mac+ANSI libraries
254 ---- ( cut here ) ---- gc_prefix_testlib.h -- all libs -----
255 #define MSL_USE_PRECOMPILED_HEADERS 0
256 #include <ansi_prefix.mac.h>
259 #define ALL_INTERIOR_POINTERS /* for GC_priv.h */
260 ---- ( cut here ) ----
262 3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'.
264 The test app is just an ordinary ANSI-C console app. Make sure settings match
265 the library you're testing.
270 the GC library to test -- link order before ANSI libs
271 suitable Mac+ANSI libraries
277 For convenience I used one test-project with several targets so that all
278 test apps are build at once. Two for each library to test: test.c and
279 gc_app.cc. When I was satisfied that the libraries were ok. I put the
280 libraries + gc.h + the c++ interface-file in a folder that I then put into
281 the MSL hierarchy so that I don't have to alter access-paths in projects
284 After that, just add the proper GC library to your project and the GC is in
285 action! malloc will call GC_malloc and free GC_free, new/delete too. You
286 don't have to call free or delete. You may have to be a bit cautious about
287 delete if you're freeing other resources than RAM. See gc_cpp.h. You can
288 also keep coding as always with delete/free. That works too. If you want,
289 "include <gc.h> and tweak it's use a bit.
293 It has been a while since I tried the GC in SPM, but I think that the above
294 instructions should be sufficient to guide you through in SPM too. SPM
295 needs to know where the global data is. Use the files 'datastart.c' and
296 'dataend.c'. Put 'datastart.c' at the top of your project and 'dataend.c'
297 at the bottom of your project so that all data is surrounded. This is not
298 needed in Codewarrior because it provides intrinsic variables
299 __datastart__, __data_end__ that wraps all globals.
301 Source Changes (GC 4.12a2)
302 ==========================
303 Very few. Just one tiny in the GC, not strictly needed.
304 - MacOS.c line 131 in routine GC_MacFreeTemporaryMemory()
305 change # if !defined(SHARED_LIBRARY_BUILD)
306 to # if !defined(SILENT) && !defined(SHARED_LIBRARY_BUILD)
307 To turn off a message when the application quits (actually, I faked
308 this change by #defining SHARED_LIBRARY_BUILD in a statically linked
309 library for more than a year without ill effects but perhaps this is
313 made the first lines of main() look like this:
315 int main( int argc, char* argv[] ) {
317 #if macintosh // MacOS
318 char* argv_[] = {"test_cpp","10"}; // doesn't
319 argv=argv_; // have a
320 argc = sizeof(argv_)/sizeof(argv_[0]); // commandline
325 alloc dummy_to_fool_the_compiler_into_doing_things_it_currently_cant_handle;
328 - config.h [now gcconfig.h]
329 __MWERKS__ does not have to mean MACOS. You can use Codewarrior to
330 build a Win32 or BeOS library and soon a Rhapsody library. You may
331 have to change that #if...
335 It worked for me, hope it works for you.
339 ----------------------------------------------------------------------------
342 Patrick Beard's instructions (may be dated):
344 v4.3 of the collector now runs under Symantec C++/THINK C v7.0.4, and
345 Metrowerks C/C++ v4.5 both 68K and PowerPC. Project files are provided
346 to build and test the collector under both development systems.
351 To configure the collector, under both development systems, a prefix file
352 is used to set preprocessor directives. This file is called "MacOS_config.h".
353 Also to test the collector, "MacOS_Test_config.h" is provided.
358 To test the collector (always a good idea), build one of the gctest projects,
359 gctest.¹ (Symantec C++/THINK C), mw/gctest.68K.¹, or mw/gctest.PPC.¹. The
360 test will ask you how many times to run; 1 should be sufficient.
365 For your convenience project files for the major Macintosh development
366 systems are provided.
368 For Symantec C++/THINK C, you must build the two projects gclib-1.¹ and
369 gclib-2.¹. It has to be split up because the collector has more than 32k
370 of static data and no library can have more than this in the Symantec
371 environment. (Future versions will probably fix this.)
373 For Metrowerks C/C++ 4.5 you build gc.68K.¹/gc.PPC.¹ and the result will
374 be a library called gc.68K.lib/gc.PPC.lib.
379 Under Symantec C++/THINK C, you can just add the gclib-1.¹ and gclib-2.¹
380 projects to your own project. Under Metrowerks, you add gc.68K.lib or
381 gc.PPC.lib and two additional files. You add the files called datastart.c
382 and dataend.c to your project, bracketing all files that use the collector.
383 See mw/gctest.¹ for an example.
385 Include the projects/libraries you built above into your own project,
386 #include "gc.h", and call GC_malloc. You don't have to call GC_free.