[BACK]Return to README.Mac CVS log [TXT][DIR] Up to [local] / OpenXM_contrib2 / asir2000 / gc

Annotation of OpenXM_contrib2/asir2000/gc/README.Mac, Revision 1.1.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>