2000-07-19 H.J. Lu <hjl@gnu.org>
[binutils.git] / mpw-README
blob767140b5b2632a3d630ad010af2afaa5371c3e2b
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.
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.)
9 INSTALLING GNU TOOLS
11 * System Requirements
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.
20 * Automated Installation
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.
27 The Install script does not alter anything in the System Folder, and
28 it does not take any action without confirmation.
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.)
36 * Manual Installation
38 If you don't want to run the Install script, you can do installation
39 manually; this section describes the steps involved.
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:
45         set Commands "{Boot}Cygnus:latest:bin:,{Commands}"
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
51         :lib:gcc-lib:<target>:cygnus-<version>:
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:
65         set GCC_EXEC_PREFIX MyDisk:Stuff:lib:gcc-lib:
66         export GCC_EXEC_PREFIX
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.
76 USING GNU TOOLS
78 * Using Native PowerMac GCC
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.
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:
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
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.
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:
108 #include "CodeFragmentTypes.r"
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         }
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.
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.
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'.
134 MPW GCC supports the usual Pascal-style strings and alignment pragmas.
136 To find standard include files you can set the variable GCCIncludes:
138         set GCCIncludes MyDisk:MyIncludes:
139         export GCCIncludes
141 GCCIncludes is similar to MPW's CIncludes or CW's MWCIncludes.  In
142 order to use MPW's usual include files, just say:
144         set GCCIncludes "{CIncludes}"
145         export GCCIncludes
147 * Using GCC as a Cross-Compiler
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
153         gC foo.c
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.
159 Note that using MPW include files with a cross-compiler is somewhat
160 dangerous.
162 * Using the Assembler and Friends
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.)
170 * Using GDB
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.
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.
183 BUILDING GNU TOOLS
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:".
192 * Requirements for Building
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:
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
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.
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:
221         set Commands "{Boot}Cygnus:buildtools:,{Commands}"
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:
226         Set FLEX_SKELETON "{Boot}"Cygnus:buildtools:Flex.skel
227         Export FLEX_SKELETON
229 * Configuring
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:
235         {Boot}Cygnus:src:mpw-configure --target <name> --cc <compiler> --srcdir {Boot}Cygnus:src: --prefix <whatever>
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.
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.
247 <compiler> must be the name of the compiler to use.  It defaults to "mpwc".
249         (m68k)
250         mpwc    MPW C
251         sc68k   Symantec C
252         mwc68k  Metrowerks C (Codewarrior)
253         gcc68k  GCC
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
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.
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.
271 As an example, here is the configure line that you could use to build
272 native PowerMac GCC:
274 "{Boot}"Cygnus:src:mpw-configure --cc mwcppc --target powerpc-apple-macos --srcdir "{Boot}"Cygnus:src: --prefix "{Boot}"GNUTools:
276 * Building
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.
287 The command
289         mpw-build
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.
294 You may see some warnings; these are mostly likely benign, typically
295 disagreements about declarations of library and system functions.
297 * Installing
299 To install the just-built tools, use the command
301         mpw-build install
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.
313 * Known Problems With Using Various Compilers to Build
315 Most versions of MPW C have problems with compiling GNU software.
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.
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.
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).
331 Versions of MPW Make earlier than 4.0d2 have exhibited bizarre behavior,
332 failure to substitute variables and the like.
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.
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.
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}.
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.
349 KNOWN BUGS
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.
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.
360 '/' or ' ' embedded in any device, directory, or file name may or may
361 not work.
363 objcopy -O srec foo.o makes random output filenames.
365 Mac-x-mips requires -mgas but Unix hosts don't.
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.
370 GDB doesn't seem to use the printer port correctly, although it tries.
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:
375         set MEASURE_SPIN all
376         export MEASURE_SPIN