mpw-README

   1 This is basic information about the Macintosh(tm) MPW(tm) port of the
   2 GNU tools.  The information below applies to both native and cross
   3 compilers.
   4
   5 (Please note that there are two versions of this file; "mpw-README"
   6 is the source form, and "Read Me for MPW" is the distribution form.
   7 "Read Me for MPW" has 8-bit chars such as \Option-d embedded in it.)
   8
   9 INSTALLING GNU TOOLS
  10
  11 * System Requirements
  12
  13 To use these tools, you will need a Mac with a 68020 or better or else
  14 any PowerMac, System 7.1 or later, and MPW 3.3 or 3.4.  You will *not*
  15 need any other MPW compiler unless you want to rebuild from sources,
  16 nor even any include files, unless you are building actual Mac
  17 applications.  For PowerMac native you will need PPCLink, however;
  18 also the executables are PowerPC-only.
  19
  20 * Automated Installation
  21
  22 The simplest way to install GNU tools is to run the Install script.
  23 The script will copy things to where you want to keep them, will build
  24 a UserStartup file with settings corresponding to where things were
  25 copied, and offer to put that UserStartup file in your MPW folder.
  26
  27 The Install script does not alter anything in the System Folder, and
  28 it does not take any action without confirmation.
  29
  30 The Install script will be at the top level of the binary
  31 distribution, or at the top level of the object directory if
  32 rebuilding from source.  (The sources include a file called
  33 "mpw-install" at the top level, but it is the source to the Install
  34 script and cannot be run directly.)
  35
  36 * Manual Installation
  37
  38 If you don't want to run the Install script, you can do installation
  39 manually; this section describes the steps involved.
  40
  41 The GNU tools can go in any directory that is in your {Commands} list.
  42 We generally put all the tools somewhere like {Boot}Cygnus:latest:bin,
  43 and then add to a UserStartup file:
  44
  45         set Commands "{Boot}Cygnus:latest:bin:,{Commands}"
  46
  47 However, the cpp and cc1 programs of GCC are not normally stored here.
  48 Instead, they will be in a "lib" directory that is alongside "bin",
  49 and organized by target and version underneath, with names like
  50
  51         :lib:gcc-lib:<target>:cygnus-<version>:
  52
  53 If you build and install everything yourself according to the build
  54 instructions below, then you will not have any problems.  However, you
  55 may discover that GCC seems unable to find the right cpp and cc1;
  56 usually this will be because directory names have changed.  (Even
  57 renaming your hard disk will make this happen.)  In such cases, you
  58 have several choices.  One is just to add this directory to
  59 {Commands}, but then you will not be able to get any other cpp or cc1,
  60 such as those used by a different target or version.  Another way is
  61 to rename your disk and directories to match the prefix used when the
  62 tools were compiled.  Finally, you can set the variable
  63 GCC_EXEC_PREFIX to point to the library directory:
  64
  65         set GCC_EXEC_PREFIX MyDisk:Stuff:lib:gcc-lib:
  66         export GCC_EXEC_PREFIX
  67
  68 You may also want to edit MPW's HEXA 128 resource.  When GCC is built
  69 using a native GCC, it is compiled to use a special stack allocator
  70 function alloca().  While this is very efficient, it means that GCC
  71 will need considerable stack space to run, especially when compiling
  72 large programs with optimization turned on.  You give MPW more stack
  73 by editing the HEXA 128 resource of the MPW Shell.  A value of "0008
  74 0000" gives 512K of stack size, which is usually sufficient.
  75
  76 USING GNU TOOLS
  77
  78 * Using Native PowerMac GCC
  79
  80 Using a native PowerMac GCC to produce MPW tools or MacOS applications
  81 is more complicated than just "gC foo.c", although no more complicated
  82 than with other Mac compilers.
  83
  84 To build a native PowerMac MPW tool, use this sequence, where hello.c
  85 is the usual "hello world" program, and genericcfrg.r is the Rez file
  86 with the code fragment resource:
  87
  88 gC -I{CIncludes} -fno-builtin -Dpascal= -c -g hello.c
  89 PPCLink hello.o -o hello \Option-d
  90         "{PPCLibraries}"StdCRuntime.o \Option-d
  91         "{SharedLibraries}"InterfaceLib \Option-d
  92         "{SharedLibraries}"StdCLib \Option-d
  93         "{PPCLibraries}"PPCToolLibs.o \Option-d
  94         "{PPCLibraries}"PPCCRuntime.o \Option-d
  95         "{GCCPPCLibraries}"libgcc.xcoff
  96 rez -d APPNAME='"'hello'"' GenericCFRG.r -o hello
  97 setfile -t 'MPST' -c 'MPS ' hello
  98
  99 The same sequence works to build a MacOS application, but you set the file
 100 type to 'APPL' and don't link in PPCToolLibs.o.  For further details on
 101 using MPW to build Mac applications, see the general MPW documentation.
 102
 103 Recent versions of PPCLink have an option to generate the code
 104 fragment resource and automatically set creator and file type;
 105 here is what GenericCFRG.r should look like if you have an older
 106 PPCLink or are using GNU ld:
 107
 108 #include "CodeFragmentTypes.r"
 109
 110 resource 'cfrg' (0) {
 111         {
 112                 kPowerPC,
 113                 kFullLib,
 114                 kNoVersionNum,kNoVersionNum,
 115                 0,0,
 116                 kIsApp,kOnDiskFlat,kZeroOffset,kWholeFork,
 117                 APPNAME // must be defined on Rez command line with -d option
 118         }
 119 };
 120
 121 In general this port of GCC supports the same option syntax and
 122 behavior as its Unix counterpart.  It also has similar compilation
 123 rules, so it will run the assembler on .s files and so forth.
 124
 125 The GCC manual includes full information on the available options.
 126 One option that may be especially useful is "-v", which shows you what
 127 tools and options are being used; unlike most Mac C compilers, GCC
 128 directs assembly and linking in addition to compilation.
 129
 130 MPW GCC does feature two extensions to the option syntax; '-d macro=name'
 131 works just as '-Dmacro=name' does in Unix, and '-i directory' works the
 132 same as '-Idirectory'.
 133
 134 MPW GCC supports the usual Pascal-style strings and alignment pragmas.
 135
 136 To find standard include files you can set the variable GCCIncludes:
 137
 138         set GCCIncludes MyDisk:MyIncludes:
 139         export GCCIncludes
 140
 141 GCCIncludes is similar to MPW's CIncludes or CW's MWCIncludes.  In
 142 order to use MPW's usual include files, just say:
 143
 144         set GCCIncludes "{CIncludes}"
 145         export GCCIncludes
 146
 147 * Using GCC as a Cross-Compiler
 148
 149 If you have a cross-compiler, and you have all of the correct
 150 target-side crt0 and libraries available, then to compile and link a
 151 file "foo.c", you can say just
 152
 153         gC foo.c
 154
 155 The output file will be an MPW binary file named "a.out"; the format
 156 of the contents will depend on which target is in use, so for instance
 157 a MIPS-targeting GCC will produce ECOFF or ELF executables.
 158
 159 Note that using MPW include files with a cross-compiler is somewhat
 160 dangerous.
 161
 162 * Using the Assembler and Friends
 163
 164 The assembler ("as") and linker ("ld") are faithful ports of their
 165 Unix counterparts.  Similarly, the binutils "ar", "cplusfilt", "nm",
 166 "objcopy", "objdump", "ranlib", "size", "strings", and "strip" are all
 167 like they are under Unix.  (Note that "cplusfilt" is usually called
 168 "c++filt" under Unix.)
 169
 170 * Using GDB
 171
 172 There are two flavors of GDB.  "gdb" is an MPW tool that works very
 173 much like it does in Unix; put a command into the MPW worksheet and
 174 type the <enter> key to send it to GDB.  While "gdb" is running, you
 175 cannot do anything else in MPW, although you can switch to other
 176 Mac applications and use them.
 177
 178 "SiowGDB" is also a Mac application, but it is GDB using the SIOW
 179 package to provide console emulation.  Commands are exactly as for the
 180 MPW tool, but since this is its own application, you can switch
 181 between it and MPW.
 182
 183 BUILDING GNU TOOLS
 184
 185 This port of the GNU tools uses a configure script similar to
 186 that used for GNU tools under Unix, but rewritten for MPW.  As with
 187 Unix configuration, there is an "object" directory that may be
 188 different from the "source" directory.  In the example commands below,
 189 we will assume that we are currently in the object directory, and that
 190 the source directory is "{Boot}Cygnus:src:".
 191
 192 * Requirements for Building
 193
 194 In addition to the sources, you will need a set of tools that the
 195 configure and build scripts assume to be available.  These tools
 196 (and their versions, if relevant) are as follows:
 197
 198         byacc tool
 199         flex (2.3.7) tool (and Flex.skel file)
 200         forward-include script
 201         MoveIfChange script
 202         mpw-touch script
 203         mpw-true script
 204         NewFolderRecursive script
 205         null-command script
 206         open-brace script
 207         sed (1.13) tool
 208         tr-7to8 script
 209         true script
 210
 211 The scripts are in the sources, under utils:mpw:. You must arrange to
 212 get the other tools yourself (they are readily available from the
 213 "usual" net sites, and are also on many CDROMS).  In addition, there
 214 will usually be a set of these available at ftp.cygnus.com, in pub/mac.
 215
 216 You may put the build tools in your usual Tools or Scripts
 217 directories, or keep them in a separate directories.  We prefer to
 218 make a directory called "buildtools" and we put this in one of our
 219 UserStartup files:
 220
 221         set Commands "{Boot}Cygnus:buildtools:,{Commands}"
 222
 223 Flex uses an environment variable FLEX_SKELETON to locate its skeleton
 224 file, so you need to do something like this, preferably in a UserStartup:
 225
 226         Set FLEX_SKELETON "{Boot}"Cygnus:buildtools:Flex.skel
 227         Export FLEX_SKELETON
 228
 229 * Configuring
 230
 231 Before you can build anything, you must configure.  You do this by
 232 creating an directory where object files will be stored, setdirectory
 233 to that directory and do a configure command:
 234
 235         {Boot}Cygnus:src:mpw-configure --target <name> --cc <compiler> --srcdir {Boot}Cygnus:src: --prefix <whatever>
 236
 237 If the source directory is not in your {Commands} list, then you must
 238 supply a full pathname to mpw-configure, since mpw-configure invokes
 239 itself after switching into each subdirectory.  Using a relative
 240 pathname, even something like ':mpw-configure', will therefore not work.
 241
 242 <name> must be a known target.  Valid ones include "m68k-apple-macos",
 243 "powerpc-apple-macos", "i386-unknown-go32", "mips-idt-ecoff", and
 244 "sh-hitachi-hms".  Not all target types are accepted for all of the
 245 tools yet.
 246
 247 <compiler> must be the name of the compiler to use.  It defaults to "mpwc".
 248
 249         (m68k)
 250         mpwc    MPW C
 251         sc68k   Symantec C
 252         mwc68k  Metrowerks C (Codewarrior)
 253         gcc68k  GCC
 254
 255         (powerpc)
 256         ppcc    PPCC
 257         mrc     Macintosh on RisC (Mister C, aka(?) Frankenstein)
 258         scppc   Symantec C
 259         mwcppc  Metrowerks C (Codewarrior)
 260         gccppc  GCC
 261
 262 Not all compilers will compile all tools equally well!  For m68k Macs,
 263 MPW C has the best record so far (it has problems, but they can be
 264 worked around), while for PowerMacs, CodeWarrior is the only compiler
 265 that has successfully compiled everything into running code.
 266
 267 <prefix> is the path that "gcc" will prepend when looking for tools
 268 to execute.  GCC_EXEC_PREFIX overrides this value, so you need not
 269 include it if you plan to use GCC_EXEC_PREFIX.
 270
 271 As an example, here is the configure line that you could use to build
 272 native PowerMac GCC:
 273
 274 "{Boot}"Cygnus:src:mpw-configure --cc mwcppc --target powerpc-apple-macos --srcdir "{Boot}"Cygnus:src: --prefix "{Boot}"GNUTools:
 275
 276 * Building
 277
 278 If you use CodeWarrior, you *must* first set MWCIncludes to
 279 {CIncludes}.  This is because you will be building MPW tools, and
 280 their standard I/O works by making references to data that is part of
 281 the MPW Shell, which means that the code must be compiled and linked
 282 with macros that refer to that data, and those macros are in
 283 {CIncludes}, not the default {MWCIncludes}.  Without this change, you
 284 will encounter problems compiling libiberty/mpw.c, but tweaking that
 285 file only masks the real problem, and does not fix it.
 286
 287 The command
 288
 289         mpw-build
 290
 291 will build everything. Building will take over an hour on a Quadra 800
 292 or PowerMac 8100/110, longer if the sources are on a shared volume.
 293
 294 You may see some warnings; these are mostly likely benign, typically
 295 disagreements about declarations of library and system functions.
 296
 297 * Installing
 298
 299 To install the just-built tools, use the command
 300
 301         mpw-build install
 302
 303 This part of the installation procedure just copies files to the
 304 location specified at configure time by <prefix>, and, in some cases,
 305 renames them from temporary internal names to their usual names. This
 306 install process is *not* the same as what the Install script does;
 307 Install can copy tools from the installation location chosen at
 308 configuration time to a user-chosen place, and sets up a UserStartup
 309 file.  Note that while the Install script is optional, the install
 310 build action performs some tasks would be very hard to replicate
 311 manually, so you should always do it before using the tools.
 312
 313 * Known Problems With Using Various Compilers to Build
 314
 315 Most versions of MPW C have problems with compiling GNU software.
 316
 317 MPW C 3.2.x has preprocessing bugs that render it incapable of
 318 compiling the BFD library, so it can't be used at all for building BFD.
 319
 320 MPW C 3.3, 3.3.1, and 3.3.2 will spontaneously claim to have found
 321 errors in the source code, but in fact the code is perfectly fine.  If
 322 this happens, just set the working directory back to the top-level
 323 objdir (where the configure command above was performed), and type
 324 "mpw-build all" again.  If it goes on through the supposed error, then
 325 you got one of the spurious errors.  A full build may require a number
 326 of these restarts.
 327
 328 MPW C 3.3.3 seems to work OK, at least with the aid of a number of
 329 workarounds that are in the sources (look for #ifdef MPW_C).
 330
 331 Versions of MPW Make earlier than 4.0d2 have exhibited bizarre behavior,
 332 failure to substitute variables and the like.
 333
 334 Metrowerks CW6 PPC linker (MWLinkPPC) seems to do bad things with memory
 335 if the "Modern Memory Manager" is turned on (in the Memory control panel),
 336 but works OK if it is turned off.
 337
 338 Metrowerks CW6 loses bigtime compiling opcodes:ppc-opc.c, which has
 339 some deeply nested macros.  (CW7 is OK.)  There is a way to patch the
 340 file, by substituting constant values.  If you need to do this,
 341 contact shebs@cygnus.com for details.
 342
 343 <Gestalt.h> is missing from {CIncludes} in the MPW version that comes
 344 with CW7.  You can just copy the one in CW7's {MWCIncludes}.
 345
 346 CW8 and later have changes to headers and such that will require changes
 347 to the source in order to be able to use them to rebuild.
 348
 349 KNOWN BUGS
 350
 351 The declarations for memcpy and memcmp in some versions of header files
 352 may conflict with GCC's builtin definition.  Either use -fno-builtin
 353 or ignore the warnings.
 354
 355 This is not a bug, but - watch out for cr/nl translation!  For instance,
 356 if config/mpw-mh-mpw is not properly translated because it has been
 357 copied or updated separately, then everything will almost build, but
 358 you will get puzzling error messages from make or the compiler.
 359
 360 '/' or ' ' embedded in any device, directory, or file name may or may
 361 not work.
 362
 363 objcopy -O srec foo.o makes random output filenames.
 364
 365 Mac-x-mips requires -mgas but Unix hosts don't.
 366
 367 GDB will frequently require a '/' on the front of a device name in order
 368 to recognize it as an absolute rather than a relative pathname.
 369
 370 GDB doesn't seem to use the printer port correctly, although it tries.
 371
 372 The cursor doesn't always spin as much as it should.  To get elaborate
 373 statistics and warnings about spin rates, add this to UserStartup:
 374
 375         set MEASURE_SPIN all
 376         export MEASURE_SPIN