| 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 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 file |
| 15 |
:extra:Mac_files:MacOS_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 |
Codewarrior: CWPro1 |
| 28 |
date: 18 July 1997 |
| 29 |
|
| 30 |
The notes may or may not apply to earlier or later versions of the CWPro. |
| 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 |
|
| 38 |
Porting to MacOS is a bit more complex than it first seems. Which MacOS? |
| 39 |
68K/PowerPC? Which compiler? Each supports both 68K and PowerPC and offer a |
| 40 |
large number of (unique to each environment) compiler settings. Each |
| 41 |
combination of compiler/68K/PPC/settings require a unique combination of |
| 42 |
standard libraries. And the IDE's does not select them for you. They don't |
| 43 |
even check that the library is built with compatible setting and this is |
| 44 |
the major source of problems when porting the GC (and otherwise too). |
| 45 |
|
| 46 |
You will have to make choices when you configure the GC. I've made some |
| 47 |
choices here, but there are other combinations of settings and #defines |
| 48 |
that work too. |
| 49 |
|
| 50 |
As for target settings the major obstacles may be: |
| 51 |
- 68K Processor: check "4-byte Ints". |
| 52 |
- PPC Processor: uncheck "Store Static Data in TOC". |
| 53 |
|
| 54 |
What you need to do: |
| 55 |
1) Build the GC as a library |
| 56 |
2) Test that the library works with 'test.c'. |
| 57 |
3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc'. |
| 58 |
|
| 59 |
== 1. The Libraries == |
| 60 |
|
| 61 |
I made one project with four targets (68K/PPC tempmem or appheap). One target |
| 62 |
will suffice if you're able to decide which one you want. I wasn't... |
| 63 |
|
| 64 |
Codewarrior allows a large number of compiler/linker settings. I used these: |
| 65 |
|
| 66 |
Settings shared by all targets: |
| 67 |
------------------------------ |
| 68 |
o Access Paths: |
| 69 |
- User Paths: the GC folder |
| 70 |
- System Paths: {Compiler}:Metrowerks Standard Library: |
| 71 |
{Compiler}:MacOS Support:Headers: |
| 72 |
{Compiler}:MacOS Support:MacHeaders: |
| 73 |
o C/C++ language: |
| 74 |
- inlining: normal |
| 75 |
- direct to SOM: off |
| 76 |
- enable/check: exceptions, RTTI, bool (and if you like pool strings) |
| 77 |
|
| 78 |
PowerPC target settings |
| 79 |
----------------------- |
| 80 |
o Target Settings: |
| 81 |
- name of target |
| 82 |
- MacOS PPC Linker |
| 83 |
o PPC Target |
| 84 |
- name of library |
| 85 |
o C/C++ language |
| 86 |
- prefix file as described below |
| 87 |
o PPC Processor |
| 88 |
- Struct Alignment: PowerPC |
| 89 |
- uncheck "Store Static Data in TOC" -- important! |
| 90 |
I don't think the others matter, I use full optimization and it is OK |
| 91 |
o PPC Linker |
| 92 |
- Factory Settings (SYM file with full paths, faster linking, dead-strip |
| 93 |
static init, Main: __start) |
| 94 |
|
| 95 |
|
| 96 |
68K target settings |
| 97 |
------------------- |
| 98 |
o Target Settings: |
| 99 |
- name of target |
| 100 |
- MacOS 68K Linker |
| 101 |
o 68K Target |
| 102 |
- name of library |
| 103 |
- A5 relative data |
| 104 |
o C/C++ language |
| 105 |
- prefix file as described below |
| 106 |
o 68K Processor |
| 107 |
- Code model: smart |
| 108 |
- Struct alignment: 68K |
| 109 |
- FP: SANE |
| 110 |
- enable 4-Byte Ints -- important! |
| 111 |
I don't think the others matter. I selected... |
| 112 |
- enable: 68020 |
| 113 |
- enable: global register allocation |
| 114 |
o IR Optimizer |
| 115 |
- enable: Optimize Space, Optimize Speed |
| 116 |
I suppose the others would work too, but haven't tried... |
| 117 |
o 68K Linker |
| 118 |
- Factory Settings (New Style MacsBug, SYM file with full paths, |
| 119 |
A6 Frames, fast link, Merge compiler glue into segment 1, |
| 120 |
dead-strip static init) |
| 121 |
|
| 122 |
Prefix Files to configure the GC sources |
| 123 |
---------------------------------------- |
| 124 |
The Codewarrior equivalent of command-line compilers -DNAME=X is to use |
| 125 |
prefix-files. A TEXT file that is automatically #included before the first byte |
| 126 |
of every source file. I used these: |
| 127 |
|
| 128 |
---- ( cut here ) ---- gc_prefix_tempmem.h -- 68K and PPC ----- |
| 129 |
#include "gc_prefix_common.h" |
| 130 |
#undef USE_TEMPORARY_MEMORY |
| 131 |
#define USE_TEMPORARY_MEMORY |
| 132 |
---- ( cut here ) ---- gc_prefix_appmem.h -- 68K and PPC ----- |
| 133 |
#include "gc_prefix_common.h" |
| 134 |
#undef USE_TEMPORARY_MEMORY |
| 135 |
// #define USE_TEMPORARY_MEMORY |
| 136 |
|
| 137 |
---- ( cut here ) ---- gc_prefix_common.h -------------------- |
| 138 |
// gc_prefix_common.h |
| 139 |
// ------------------ |
| 140 |
// Codewarrior prefix file to configure the GC libraries |
| 141 |
// |
| 142 |
// prefix files are the Codewarrior equivalent of the |
| 143 |
// command line option -Dname=x frequently seen in makefiles |
| 144 |
|
| 145 |
#if !__MWERKS__ |
| 146 |
#error only tried this with Codewarrior |
| 147 |
#endif |
| 148 |
|
| 149 |
#if macintosh |
| 150 |
#define MSL_USE_PRECOMPILED_HEADERS 0 |
| 151 |
#include <ansi_prefix.mac.h> |
| 152 |
|
| 153 |
// See list of #defines to configure the library in: 'MakeFile' |
| 154 |
// see also README |
| 155 |
|
| 156 |
#define ALL_INTERIOR_POINTERS // follows interior pointers. |
| 157 |
//#define DONT_ADD_BYTE_AT_END // disables the padding if defined. |
| 158 |
//#define SMALL_CONFIG // whether to use a smaller heap. |
| 159 |
#define GC_ATOMIC_UNCOLLECTABLE // GC_malloc_atomic_uncollectable() |
| 160 |
|
| 161 |
// define either or none as per personal preference |
| 162 |
// used in malloc.c |
| 163 |
#define REDIRECT_MALLOC GC_malloc |
| 164 |
//#define REDIRECT_MALLOC GC_malloc_uncollectable |
| 165 |
// if REDIRECT_MALLOC is #defined make sure that the GC library |
| 166 |
// is listed before the ANSI/ISO libs in the Codewarrior |
| 167 |
// 'Link order' panel |
| 168 |
//#define IGNORE_FREE |
| 169 |
|
| 170 |
// mac specific configs |
| 171 |
//#define USE_TEMPORARY_MEMORY // use Macintosh temporary memory. |
| 172 |
//#define SHARED_LIBRARY_BUILD // build for use in a shared library. |
| 173 |
|
| 174 |
#else |
| 175 |
// could build Win32 here too, or in the future |
| 176 |
// Rhapsody PPC-mach, Rhapsody PPC-MacOS, |
| 177 |
// Rhapsody Intel-mach, Rhapsody Intel-Win32,... |
| 178 |
// ... ugh this will get messy ... |
| 179 |
#endif |
| 180 |
|
| 181 |
// make sure ints are at least 32-bit |
| 182 |
// ( could be set to 16-bit by compiler settings (68K) ) |
| 183 |
|
| 184 |
struct gc_private_assert_intsize_{ char x[ sizeof(int)>=4 ? 1 : 0 ]; }; |
| 185 |
|
| 186 |
#if __powerc |
| 187 |
#if __option(toc_data) |
| 188 |
#error turn off "store static data in TOC" when using GC |
| 189 |
// ... or find a way to add TOC to the root set...(?) |
| 190 |
#endif |
| 191 |
#endif |
| 192 |
---- ( cut here ) ---- end of gc_prefix_common.h ----------------- |
| 193 |
|
| 194 |
Files to build the GC libraries: |
| 195 |
-------------------------------- |
| 196 |
allchblk.c |
| 197 |
alloc.c |
| 198 |
blacklst.c |
| 199 |
checksums.c |
| 200 |
dbg_mlc.c |
| 201 |
finalize.c |
| 202 |
fnlz_mlc.c |
| 203 |
headers.c |
| 204 |
mach_dep.c |
| 205 |
extra/MacOS.c -- contains MacOS code |
| 206 |
malloc.c |
| 207 |
mallocx.c |
| 208 |
mark.c |
| 209 |
mark_rts.c |
| 210 |
misc.c |
| 211 |
new_hblk.c |
| 212 |
obj_map.c |
| 213 |
os_dep.c -- contains MacOS code |
| 214 |
ptr_chck.c |
| 215 |
reclaim.c |
| 216 |
typd_mlc.c |
| 217 |
gc_badalc.cc |
| 218 |
gc_cpp.cc |
| 219 |
|
| 220 |
== 2. Test that the library works with 'test.c' == |
| 221 |
|
| 222 |
The test app is just an ordinary ANSI-C console app. Make sure settings |
| 223 |
match the library you're testing. |
| 224 |
|
| 225 |
Files |
| 226 |
----- |
| 227 |
test.c |
| 228 |
the GC library to test -- link order before ANSI libs |
| 229 |
suitable Mac+ANSI libraries |
| 230 |
|
| 231 |
prefix: |
| 232 |
------ |
| 233 |
---- ( cut here ) ---- gc_prefix_testlib.h -- all libs ----- |
| 234 |
#define MSL_USE_PRECOMPILED_HEADERS 0 |
| 235 |
#include <ansi_prefix.mac.h> |
| 236 |
#undef NDEBUG |
| 237 |
|
| 238 |
#define ALL_INTERIOR_POINTERS /* for GC_priv.h */ |
| 239 |
---- ( cut here ) ---- |
| 240 |
|
| 241 |
== 3. Test that the C++ interface 'gc_cpp.cc/h' works with 'test_cpp.cc' == |
| 242 |
|
| 243 |
The test app is just an ordinary ANSI-C console app. Make sure settings match |
| 244 |
the library you're testing. |
| 245 |
|
| 246 |
Files |
| 247 |
----- |
| 248 |
test_cpp.cc |
| 249 |
the GC library to test -- link order before ANSI libs |
| 250 |
suitable Mac+ANSI libraries |
| 251 |
|
| 252 |
prefix: |
| 253 |
------ |
| 254 |
same as for test.c |
| 255 |
|
| 256 |
For convenience I used one test-project with several targets so that all |
| 257 |
test apps are build at once. Two for each library to test: test.c and |
| 258 |
gc_app.cc. When I was satisfied that the libraries were OK. I put the |
| 259 |
libraries + gc.h + the c++ interface-file in a folder that I then put into |
| 260 |
the MSL hierarchy so that I don't have to alter access-paths in projects |
| 261 |
that use the GC. |
| 262 |
|
| 263 |
After that, just add the proper GC library to your project and the GC is in |
| 264 |
action! malloc will call GC_malloc and free GC_free, new/delete too. You |
| 265 |
don't have to call free or delete. You may have to be a bit cautious about |
| 266 |
delete if you're freeing other resources than RAM. See gc_cpp.h. You can |
| 267 |
also keep coding as always with delete/free. That works too. If you want, |
| 268 |
include "gc.h" and tweak its use a bit. |
| 269 |
|
| 270 |
== Symantec SPM == |
| 271 |
|
| 272 |
It has been a while since I tried the GC in SPM, but I think that the above |
| 273 |
instructions should be sufficient to guide you through in SPM too. SPM |
| 274 |
needs to know where the global data is. Use the files 'datastart.c' and |
| 275 |
'dataend.c'. Put 'datastart.c' at the top of your project and 'dataend.c' |
| 276 |
at the bottom of your project so that all data is surrounded. This is not |
| 277 |
needed in Codewarrior because it provides intrinsic variables |
| 278 |
__datastart__, __data_end__ that wraps all globals. |
| 279 |
|
| 280 |
|
| 281 |
It worked for me, hope it works for you. |
| 282 |
|
| 283 |
Lars Farm |
| 284 |
---------------------------------------------------------------------------- |
| 285 |
|
| 286 |
|
| 287 |
Patrick Beard's instructions (may be dated): |
| 288 |
|
| 289 |
The collector should run under Symantec C++/THINK C v7.0.4, and |
| 290 |
Metrowerks C/C++ v4.5 both 68K and PowerPC. Project files are provided |
| 291 |
to build and test the collector under both development systems. |
| 292 |
|
| 293 |
Configuration |
| 294 |
------------- |
| 295 |
|
| 296 |
To configure the collector, under both development systems, a prefix file |
| 297 |
is used to set preprocessor directives. This file is called "MacOS_config.h". |
| 298 |
|
| 299 |
Testing |
| 300 |
------- |
| 301 |
|
| 302 |
To test the collector (always a good idea), build one of the gctest projects, |
| 303 |
gctest. (Symantec C++/THINK C), mw/gctest.68K, or mw/gctest.PPC. The |
| 304 |
test will ask you how many times to run; 1 should be sufficient. |
| 305 |
|
| 306 |
Building |
| 307 |
-------- |
| 308 |
|
| 309 |
For your convenience project files for the major Macintosh development |
| 310 |
systems are provided. |
| 311 |
|
| 312 |
For Symantec C++/THINK C, you must build the two projects gclib-1 and |
| 313 |
gclib-2. It has to be split up because the collector has more than 32 KB |
| 314 |
of static data and no library can have more than this in the Symantec |
| 315 |
environment. (Future versions will probably fix this.) |
| 316 |
|
| 317 |
For Metrowerks C/C++ 4.5 you build gc.68K/PPC and the result will |
| 318 |
be a library called gc.68K.lib/gc.PPC.lib. |
| 319 |
|
| 320 |
Using |
| 321 |
----- |
| 322 |
|
| 323 |
Under Symantec C++/THINK C, you can just add the gclib-1 and gclib-2 |
| 324 |
projects to your own project. Under Metrowerks, you add gc.68K.lib or |
| 325 |
gc.PPC.lib and two additional files. You add the files called datastart.c |
| 326 |
and dataend.c to your project, bracketing all files that use the collector. |
| 327 |
See mw/gctest for an example. |
| 328 |
|
| 329 |
Include the projects/libraries you built above into your own project, |
| 330 |
#include "gc.h", and call GC_malloc. You don't have to call GC_free. |
| 331 |
|
| 332 |
Patrick C. Beard |