Annotation of OpenXM_contrib2/asir2000/gc5.3/README.Mac, Revision 1.1
1.1 ! noro 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
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>