libgc/doc/README.Mac

   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.
   8
   9 Configuring the collector is still done by editing the files
  10 :Mac_files:MacOS_config.h and :Mac_files:MacOS_Test_config.h.
  11
  12 Lars Farm's suggestions on building the collector:
  13 ----------------------------------------------------------------------------
  14 Garbage Collection on MacOS - a manual 'MakeFile'
  15 -------------------------------------------------
  16
  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.
  21
  22     GC version:     4.12a2
  23     Codewarrior:    CWPro1
  24     date:           18 July 1997
  25
  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.
  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     mailto:         lars.farm@ite.mh.se
  38
  39     address:        Lars Farm
  40                     Krönvägen 33b
  41                     856 44 Sundsvall
  42                     Sweden
  43
  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).
  51
  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.
  55
  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".
  59
  60 What you need to do:
  61 ===================
  62
  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'.
  66
  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...
  71
  72 Codewarrior allows a large number of compiler/linker settings. I used these:
  73
  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)
  85
  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)
 102
 103
 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)
 129
 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:
 135
 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
 144
 145 ---- ( cut here ) ----  gc_prefix_common.h      --------------------
 146 // gc_prefix_common.h
 147 // ------------------
 148 // Codewarrior prefix file to configure the GC libraries
 149 //
 150 //   prefix files are the Codewarrior equivalent of the
 151 //   command line option -Dname=x frequently seen in makefiles
 152
 153 #if !__MWERKS__
 154   #error only tried this with Codewarrior
 155 #endif
 156
 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
 163
 164   //  See list of #defines to configure the library in: 'MakeFile'
 165   //  see also README
 166
 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()
 174
 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
 183
 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.
 187
 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
 194
 195 // make sure ints are at least 32-bit
 196 // ( could be set to 16-bit by compiler settings (68K) )
 197
 198 struct gc_private_assert_intsize_{ char x[ sizeof(int)>=4 ? 1 : 0 ]; };
 199
 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  -----------------
 207
 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
 234
 235 2) Test that the library works with 'test.c'.
 236 =============================================
 237
 238 The test app is just an ordinary ANSI-C console app. Make sure settings
 239 match the library you're testing.
 240
 241 Files
 242 -----
 243     test.c
 244     the GC library to test        -- link order before ANSI libs
 245     suitable Mac+ANSI libraries
 246
 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
 253
 254 #define ALL_INTERIOR_POINTERS   /* for GC_priv.h */
 255 ---- ( cut here ) ----
 256
 257 3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'.
 258
 259 The test app is just an ordinary ANSI-C console app. Make sure settings match
 260 the library you're testing.
 261
 262 Files
 263 -----
 264     test_cpp.cc
 265     the GC library to test        -- link order before ANSI libs
 266     suitable Mac+ANSI libraries
 267
 268 prefix:
 269 ------
 270 same as for test.c
 271
 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.
 278
 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.
 285
 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.
 295
 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).
 306
 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                                    //
 317
 318   int i, iters, n;
 319   # ifndef __GNUC__
 320    alloc dummy_to_fool_the_compiler_into_doing_things_it_currently_cant_handle;
 321   ------------
 322
 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...
 327
 328
 329
 330    It worked for me, hope it works for you.
 331
 332    Lars Farm
 333    18 July 1997
 334 ----------------------------------------------------------------------------
 335
 336
 337 Patrick Beard's instructions (may be dated):
 338
 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.
 342
 343 Configuration
 344 -------------
 345
 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.
 349
 350 Testing
 351 -------
 352
 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.
 356
 357 Building
 358 --------
 359
 360 For your convenience project files for the major Macintosh development
 361 systems are provided.
 362
 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.)
 367
 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.
 370
 371 Using
 372 -----
 373
 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.
 379
 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.
 382
 383
 384 Patrick C. Beard
 385 January 4, 1995