1The contents of this file are old and pertain to pre-MacOSX versions. 2You probably really wanted README.darwin. 3 4--------------------------------------------- 5 6Patrick Beard's Notes for building GC v4.12 with CodeWarrior Pro 2: 7---------------------------------------------------------------------------- 8The current build environment for the collector is CodeWarrior Pro 2. 9Projects for CodeWarrior Pro 2 (and for quite a few older versions) 10are 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 14Configuring the collector is still done by editing the file 15:extra:Mac_files:MacOS_config.h. 16 17Lars Farm's suggestions on building the collector: 18---------------------------------------------------------------------------- 19Garbage Collection on MacOS - a manual 'MakeFile' 20------------------------------------------------- 21 22Project files and IDE's are great on the Macintosh, but they do have 23problems when used as distribution media. This note tries to provide 24porting 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 31The notes may or may not apply to earlier or later versions of the 32GC/CWPro. Actually, they do apply to earlier versions of both except that 33until recently a project could only build one target so each target was a 34separate project. The notes will most likely apply to future versions too. 35Possibly with minor tweaks. 36 37This is just to record my experiences. These notes do not mean I now 38provide a supported port of the GC to MacOS. It works for me. If it works 39for you, great. If it doesn't, sorry, try again...;-) Still, if you find 40errors, please let me know. 41 42 43Porting to MacOS is a bit more complex than it first seems. Which MacOS? 4468K/PowerPC? Which compiler? Each supports both 68K and PowerPC and offer a 45large number of (unique to each environment) compiler settings. Each 46combination of compiler/68K/PPC/settings require a unique combination of 47standard libraries. And the IDE's does not select them for you. They don't 48even check that the library is built with compatible setting and this is 49the major source of problems when porting the GC (and otherwise too). 50 51You will have to make choices when you configure the GC. I've made some 52choices here, but there are other combinations of settings and #defines 53that work too. 54 55As 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 59What you need to do: 601) Build the GC as a library 612) Test that the library works with 'test.c'. 623) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'. 63 64== 1. The Libraries == 65 66I made one project with four targets (68K/PPC tempmem or appheap). One target 67will suffice if you're able to decide which one you want. I wasn't... 68 69Codewarrior allows a large number of compiler/linker settings. I used these: 70 71Settings shared by all targets: 72------------------------------ 73o 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: 78o C/C++ language: 79 - inlining: normal 80 - direct to SOM: off 81 - enable/check: exceptions, RTTI, bool (and if you like pool strings) 82 83PowerPC target settings 84----------------------- 85o Target Settings: 86 - name of target 87 - MacOS PPC Linker 88o PPC Target 89 - name of library 90o C/C++ language 91 - prefix file as described below 92o 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 96o PPC Linker 97 - Factory Settings (SYM file with full paths, faster linking, dead-strip 98 static init, Main: __start) 99 100 10168K target settings 102------------------- 103o Target Settings: 104 - name of target 105 - MacOS 68K Linker 106o 68K Target 107 - name of library 108 - A5 relative data 109o C/C++ language 110 - prefix file as described below 111o 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 119o IR Optimizer 120 - enable: Optimize Space, Optimize Speed 121 I suppose the others would work too, but haven't tried... 122o 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 127Prefix Files to configure the GC sources 128---------------------------------------- 129The Codewarrior equivalent of commandline compilers -DNAME=X is to use 130prefix-files. A TEXT file that is automatically #included before the first byte 131of 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 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 189struct 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 199Files 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 stubborn.c 221 typd_mlc.c 222 gc++.cc -- this is 'gc_cpp.cc' with less 'inline' and 223 -- throw std::bad_alloc when out of memory 224 -- gc_cpp.cc works just fine too 225 226== 2. Test that the library works with 'test.c' == 227 228The test app is just an ordinary ANSI-C console app. Make sure settings 229match the library you're testing. 230 231Files 232----- 233 test.c 234 the GC library to test -- link order before ANSI libs 235 suitable Mac+ANSI libraries 236 237prefix: 238------ 239---- ( cut here ) ---- gc_prefix_testlib.h -- all libs ----- 240#define MSL_USE_PRECOMPILED_HEADERS 0 241#include <ansi_prefix.mac.h> 242#undef NDEBUG 243 244#define ALL_INTERIOR_POINTERS /* for GC_priv.h */ 245---- ( cut here ) ---- 246 247== 3. Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc' == 248 249The test app is just an ordinary ANSI-C console app. Make sure settings match 250the library you're testing. 251 252Files 253----- 254 test_cpp.cc 255 the GC library to test -- link order before ANSI libs 256 suitable Mac+ANSI libraries 257 258prefix: 259------ 260same as for test.c 261 262For convenience I used one test-project with several targets so that all 263test apps are build at once. Two for each library to test: test.c and 264gc_app.cc. When I was satisfied that the libraries were OK. I put the 265libraries + gc.h + the c++ interface-file in a folder that I then put into 266the MSL hierarchy so that I don't have to alter access-paths in projects 267that use the GC. 268 269After that, just add the proper GC library to your project and the GC is in 270action! malloc will call GC_malloc and free GC_free, new/delete too. You 271don't have to call free or delete. You may have to be a bit cautious about 272delete if you're freeing other resources than RAM. See gc_cpp.h. You can 273also keep coding as always with delete/free. That works too. If you want, 274"include <gc.h> and tweak it's use a bit. 275 276== Symantec SPM == 277 278It has been a while since I tried the GC in SPM, but I think that the above 279instructions should be sufficient to guide you through in SPM too. SPM 280needs to know where the global data is. Use the files 'datastart.c' and 281'dataend.c'. Put 'datastart.c' at the top of your project and 'dataend.c' 282at the bottom of your project so that all data is surrounded. This is not 283needed in Codewarrior because it provides intrinsic variables 284__datastart__, __data_end__ that wraps all globals. 285 286== Source Changes (GC 4.12a2) == 287 288Very few. Just one tiny in the GC, not strictly needed. 289- test_cpp.cc 290 made the first lines of main() look like this: 291 ------------ 292 int main( int argc, char* argv[] ) { 293 #endif 294 #if macintosh // MacOS 295 char* argv_[] = {"test_cpp","10"}; // doesn't 296 argv=argv_; // have a 297 argc = sizeof(argv_)/sizeof(argv_[0]); // commandline 298 #endif // 299 300 int i, iters, n; 301 # ifndef __GNUC__ 302 alloc dummy_to_fool_the_compiler_into_doing_things_it_currently_cant_handle; 303 ------------ 304 305- config.h [now gcconfig.h] 306 __MWERKS__ does not have to mean MACOS. You can use Codewarrior to 307 build a Win32 or BeOS library and soon a Rhapsody library. You may 308 have to change that #if... 309 310 311 312 It worked for me, hope it works for you. 313 314 Lars Farm 315---------------------------------------------------------------------------- 316 317 318Patrick Beard's instructions (may be dated): 319 320v4.3 of the collector now runs under Symantec C++/THINK C v7.0.4, and 321Metrowerks C/C++ v4.5 both 68K and PowerPC. Project files are provided 322to build and test the collector under both development systems. 323 324Configuration 325------------- 326 327To configure the collector, under both development systems, a prefix file 328is used to set preprocessor directives. This file is called "MacOS_config.h". 329 330Testing 331------- 332 333To test the collector (always a good idea), build one of the gctest projects, 334gctest. (Symantec C++/THINK C), mw/gctest.68K, or mw/gctest.PPC. The 335test will ask you how many times to run; 1 should be sufficient. 336 337Building 338-------- 339 340For your convenience project files for the major Macintosh development 341systems are provided. 342 343For Symantec C++/THINK C, you must build the two projects gclib-1 and 344gclib-2. It has to be split up because the collector has more than 32k 345of static data and no library can have more than this in the Symantec 346environment. (Future versions will probably fix this.) 347 348For Metrowerks C/C++ 4.5 you build gc.68K/PPC and the result will 349be a library called gc.68K.lib/gc.PPC.lib. 350 351Using 352----- 353 354Under Symantec C++/THINK C, you can just add the gclib-1 and gclib-2 355projects to your own project. Under Metrowerks, you add gc.68K.lib or 356gc.PPC.lib and two additional files. You add the files called datastart.c 357and dataend.c to your project, bracketing all files that use the collector. 358See mw/gctest for an example. 359 360Include the projects/libraries you built above into your own project, 361#include "gc.h", and call GC_malloc. You don't have to call GC_free. 362 363Patrick C. Beard 364