gc-7.2/doc/README.Mac

   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 files
  15 :Mac_files:MacOS_config.h and :Mac_files:MacOS_Test_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     mailto:         lars.farm@ite.mh.se
  43
  44     address:        Lars Farm
  45                     Krönvägen 33b
  46                     856 44 Sundsvall
  47                     Sweden
  48
  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).
  56
  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
  59 that work too.
  60
  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".
  64
  65 What you need to do:
  66 ===================
  67
  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'.
  71
  72 1) The Libraries:
  73 =================
  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...
  76
  77 Codewarrior allows a large number of compiler/linker settings. I used these:
  78
  79 Settings shared by all targets:
  80 ------------------------------
  81 o Access Paths:
  82   - User Paths:   the GC folder
  83   - System Paths: {Compiler}:Metrowerks Standard Library:
  84                   {Compiler}:MacOS Support:Headers:
  85                   {Compiler}:MacOS Support:MacHeaders:
  86 o C/C++ language:
  87   - inlining: normal
  88   - direct to SOM: off
  89   - enable/check: exceptions, RTTI, bool (and if you like pool strings)
  90
  91 PowerPC target settings
  92 -----------------------
  93 o Target Settings:
  94   - name of target
  95   - MacOS PPC Linker
  96 o PPC Target
  97   - name of library
  98 o C/C++ language
  99   - prefix file as described below
 100 o PPC Processor
 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
 104 o PPC Linker
 105   - Factory Settings (SYM file with full paths, faster linking, dead-strip
 106     static init, Main: __start)
 107
 108
 109 68K target settings
 110 -------------------
 111 o Target Settings:
 112   - name of target
 113   - MacOS 68K Linker
 114 o 68K Target
 115   - name of library
 116   - A5 relative data
 117 o C/C++ language
 118   - prefix file as described below
 119 o 68K Processor
 120   - Code model: smart
 121   - Struct alignment: 68K
 122   - FP: SANE
 123   - enable 4-Byte Ints -- important!
 124     I don't think the others matter. I selected...
 125   - enable: 68020
 126   - enable: global register allocation
 127 o IR Optimizer
 128   - enable: Optimize Space, Optimize Speed
 129     I suppose the others would work too, but haven't tried...
 130 o 68K Linker
 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)
 134
 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:
 140
 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
 149
 150 ---- ( cut here ) ----  gc_prefix_common.h      --------------------
 151 // gc_prefix_common.h
 152 // ------------------
 153 // Codewarrior prefix file to configure the GC libraries
 154 //
 155 //   prefix files are the Codewarrior equivalent of the
 156 //   command line option -Dname=x frequently seen in makefiles
 157
 158 #if !__MWERKS__
 159   #error only tried this with Codewarrior
 160 #endif
 161
 162 #if macintosh
 163   #define MSL_USE_PRECOMPILED_HEADERS 0
 164   #include <ansi_prefix.mac.h>
 165   #ifndef __STDC__
 166     #define __STDC__ 0
 167   #endif
 168
 169   //  See list of #defines to configure the library in: 'MakeFile'
 170   //  see also README
 171
 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()
 179
 180   // define either or none as per personal preference
 181   //   used in malloc.c
 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
 188
 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.
 192
 193 #else
 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 ...
 198 #endif
 199
 200 // make sure ints are at least 32-bit
 201 // ( could be set to 16-bit by compiler settings (68K) )
 202
 203 struct gc_private_assert_intsize_{ char x[ sizeof(int)>=4 ? 1 : 0 ]; };
 204
 205 #if __powerc
 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...(?)
 209   #endif
 210 #endif
 211 ---- ( cut here ) ----  end of gc_prefix_common.h  -----------------
 212
 213 Files to  build the GC libraries:
 214 --------------------------------
 215     allchblk.c
 216     alloc.c
 217     blacklst.c
 218     checksums.c
 219     dbg_mlc.c
 220     finalize.c
 221     headers.c
 222     mach_dep.c
 223     MacOS.c    -- contains MacOS code
 224     malloc.c
 225     mallocx.c
 226     mark.c
 227     mark_rts.c
 228     misc.c
 229     new_hblk.c
 230     obj_map.c
 231     os_dep.c   -- contains MacOS code
 232     ptr_chck.c
 233     reclaim.c
 234     stubborn.c
 235     typd_mlc.c
 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
 239
 240 2) Test that the library works with 'test.c'.
 241 =============================================
 242
 243 The test app is just an ordinary ANSI-C console app. Make sure settings
 244 match the library you're testing.
 245
 246 Files
 247 -----
 248     test.c
 249     the GC library to test        -- link order before ANSI libs
 250     suitable Mac+ANSI libraries
 251
 252 prefix:
 253 ------
 254 ---- ( cut here ) ----  gc_prefix_testlib.h     -- all libs -----
 255 #define MSL_USE_PRECOMPILED_HEADERS 0
 256 #include <ansi_prefix.mac.h>
 257 #undef NDEBUG
 258
 259 #define ALL_INTERIOR_POINTERS   /* for GC_priv.h */
 260 ---- ( cut here ) ----
 261
 262 3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'.
 263
 264 The test app is just an ordinary ANSI-C console app. Make sure settings match
 265 the library you're testing.
 266
 267 Files
 268 -----
 269     test_cpp.cc
 270     the GC library to test        -- link order before ANSI libs
 271     suitable Mac+ANSI libraries
 272
 273 prefix:
 274 ------
 275 same as for test.c
 276
 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
 282 that use the GC.
 283
 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.
 290
 291 Symantec SPM
 292 ============
 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.
 300
 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
 310   better).
 311
 312 - test_cpp.cc
 313   made the first lines of main() look like this:
 314   ------------
 315   int main( int argc, char* argv[] ) {
 316   #endif
 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
 321   #endif                                    //
 322
 323   int i, iters, n;
 324   # ifndef __GNUC__
 325    alloc dummy_to_fool_the_compiler_into_doing_things_it_currently_cant_handle;
 326   ------------
 327
 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...
 332
 333
 334
 335    It worked for me, hope it works for you.
 336
 337    Lars Farm
 338    18 July 1997
 339 ----------------------------------------------------------------------------
 340
 341
 342 Patrick Beard's instructions (may be dated):
 343
 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.
 347
 348 Configuration
 349 -------------
 350
 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.
 354
 355 Testing
 356 -------
 357
 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.
 361
 362 Building
 363 --------
 364
 365 For your convenience project files for the major Macintosh development
 366 systems are provided.
 367
 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.)
 372
 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.
 375
 376 Using
 377 -----
 378
 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.
 384
 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.
 387
 388
 389 Patrick C. Beard
 390 January 4, 1995