diff options
Diffstat (limited to 'mpw-README')
| -rw-r--r-- | mpw-README | 376 |
1 files changed, 376 insertions, 0 deletions
diff --git a/mpw-README b/mpw-README new file mode 100644 index 00000000000..767140b5b26 --- /dev/null +++ b/mpw-README @@ -0,0 +1,376 @@ +This is basic information about the Macintosh(tm) MPW(tm) port of the +GNU tools. The information below applies to both native and cross +compilers. + +(Please note that there are two versions of this file; "mpw-README" +is the source form, and "Read Me for MPW" is the distribution form. +"Read Me for MPW" has 8-bit chars such as \Option-d embedded in it.) + +INSTALLING GNU TOOLS + +* System Requirements + +To use these tools, you will need a Mac with a 68020 or better or else +any PowerMac, System 7.1 or later, and MPW 3.3 or 3.4. You will *not* +need any other MPW compiler unless you want to rebuild from sources, +nor even any include files, unless you are building actual Mac +applications. For PowerMac native you will need PPCLink, however; +also the executables are PowerPC-only. + +* Automated Installation + +The simplest way to install GNU tools is to run the Install script. +The script will copy things to where you want to keep them, will build +a UserStartup file with settings corresponding to where things were +copied, and offer to put that UserStartup file in your MPW folder. + +The Install script does not alter anything in the System Folder, and +it does not take any action without confirmation. + +The Install script will be at the top level of the binary +distribution, or at the top level of the object directory if +rebuilding from source. (The sources include a file called +"mpw-install" at the top level, but it is the source to the Install +script and cannot be run directly.) + +* Manual Installation + +If you don't want to run the Install script, you can do installation +manually; this section describes the steps involved. + +The GNU tools can go in any directory that is in your {Commands} list. +We generally put all the tools somewhere like {Boot}Cygnus:latest:bin, +and then add to a UserStartup file: + + set Commands "{Boot}Cygnus:latest:bin:,{Commands}" + +However, the cpp and cc1 programs of GCC are not normally stored here. +Instead, they will be in a "lib" directory that is alongside "bin", +and organized by target and version underneath, with names like + + :lib:gcc-lib:<target>:cygnus-<version>: + +If you build and install everything yourself according to the build +instructions below, then you will not have any problems. However, you +may discover that GCC seems unable to find the right cpp and cc1; +usually this will be because directory names have changed. (Even +renaming your hard disk will make this happen.) In such cases, you +have several choices. One is just to add this directory to +{Commands}, but then you will not be able to get any other cpp or cc1, +such as those used by a different target or version. Another way is +to rename your disk and directories to match the prefix used when the +tools were compiled. Finally, you can set the variable +GCC_EXEC_PREFIX to point to the library directory: + + set GCC_EXEC_PREFIX MyDisk:Stuff:lib:gcc-lib: + export GCC_EXEC_PREFIX + +You may also want to edit MPW's HEXA 128 resource. When GCC is built +using a native GCC, it is compiled to use a special stack allocator +function alloca(). While this is very efficient, it means that GCC +will need considerable stack space to run, especially when compiling +large programs with optimization turned on. You give MPW more stack +by editing the HEXA 128 resource of the MPW Shell. A value of "0008 +0000" gives 512K of stack size, which is usually sufficient. + +USING GNU TOOLS + +* Using Native PowerMac GCC + +Using a native PowerMac GCC to produce MPW tools or MacOS applications +is more complicated than just "gC foo.c", although no more complicated +than with other Mac compilers. + +To build a native PowerMac MPW tool, use this sequence, where hello.c +is the usual "hello world" program, and genericcfrg.r is the Rez file +with the code fragment resource: + +gC -I{CIncludes} -fno-builtin -Dpascal= -c -g hello.c +PPCLink hello.o -o hello \Option-d + "{PPCLibraries}"StdCRuntime.o \Option-d + "{SharedLibraries}"InterfaceLib \Option-d + "{SharedLibraries}"StdCLib \Option-d + "{PPCLibraries}"PPCToolLibs.o \Option-d + "{PPCLibraries}"PPCCRuntime.o \Option-d + "{GCCPPCLibraries}"libgcc.xcoff +rez -d APPNAME='"'hello'"' GenericCFRG.r -o hello +setfile -t 'MPST' -c 'MPS ' hello + +The same sequence works to build a MacOS application, but you set the file +type to 'APPL' and don't link in PPCToolLibs.o. For further details on +using MPW to build Mac applications, see the general MPW documentation. + +Recent versions of PPCLink have an option to generate the code +fragment resource and automatically set creator and file type; +here is what GenericCFRG.r should look like if you have an older +PPCLink or are using GNU ld: + +#include "CodeFragmentTypes.r" + +resource 'cfrg' (0) { + { + kPowerPC, + kFullLib, + kNoVersionNum,kNoVersionNum, + 0,0, + kIsApp,kOnDiskFlat,kZeroOffset,kWholeFork, + APPNAME // must be defined on Rez command line with -d option + } +}; + +In general this port of GCC supports the same option syntax and +behavior as its Unix counterpart. It also has similar compilation +rules, so it will run the assembler on .s files and so forth. + +The GCC manual includes full information on the available options. +One option that may be especially useful is "-v", which shows you what +tools and options are being used; unlike most Mac C compilers, GCC +directs assembly and linking in addition to compilation. + +MPW GCC does feature two extensions to the option syntax; '-d macro=name' +works just as '-Dmacro=name' does in Unix, and '-i directory' works the +same as '-Idirectory'. + +MPW GCC supports the usual Pascal-style strings and alignment pragmas. + +To find standard include files you can set the variable GCCIncludes: + + set GCCIncludes MyDisk:MyIncludes: + export GCCIncludes + +GCCIncludes is similar to MPW's CIncludes or CW's MWCIncludes. In +order to use MPW's usual include files, just say: + + set GCCIncludes "{CIncludes}" + export GCCIncludes + +* Using GCC as a Cross-Compiler + +If you have a cross-compiler, and you have all of the correct +target-side crt0 and libraries available, then to compile and link a +file "foo.c", you can say just + + gC foo.c + +The output file will be an MPW binary file named "a.out"; the format +of the contents will depend on which target is in use, so for instance +a MIPS-targeting GCC will produce ECOFF or ELF executables. + +Note that using MPW include files with a cross-compiler is somewhat +dangerous. + +* Using the Assembler and Friends + +The assembler ("as") and linker ("ld") are faithful ports of their +Unix counterparts. Similarly, the binutils "ar", "cplusfilt", "nm", +"objcopy", "objdump", "ranlib", "size", "strings", and "strip" are all +like they are under Unix. (Note that "cplusfilt" is usually called +"c++filt" under Unix.) + +* Using GDB + +There are two flavors of GDB. "gdb" is an MPW tool that works very +much like it does in Unix; put a command into the MPW worksheet and +type the <enter> key to send it to GDB. While "gdb" is running, you +cannot do anything else in MPW, although you can switch to other +Mac applications and use them. + +"SiowGDB" is also a Mac application, but it is GDB using the SIOW +package to provide console emulation. Commands are exactly as for the +MPW tool, but since this is its own application, you can switch +between it and MPW. + +BUILDING GNU TOOLS + +This port of the GNU tools uses a configure script similar to +that used for GNU tools under Unix, but rewritten for MPW. As with +Unix configuration, there is an "object" directory that may be +different from the "source" directory. In the example commands below, +we will assume that we are currently in the object directory, and that +the source directory is "{Boot}Cygnus:src:". + +* Requirements for Building + +In addition to the sources, you will need a set of tools that the +configure and build scripts assume to be available. These tools +(and their versions, if relevant) are as follows: + + byacc tool + flex (2.3.7) tool (and Flex.skel file) + forward-include script + MoveIfChange script + mpw-touch script + mpw-true script + NewFolderRecursive script + null-command script + open-brace script + sed (1.13) tool + tr-7to8 script + true script + +The scripts are in the sources, under utils:mpw:. You must arrange to +get the other tools yourself (they are readily available from the +"usual" net sites, and are also on many CDROMS). In addition, there +will usually be a set of these available at ftp.cygnus.com, in pub/mac. + +You may put the build tools in your usual Tools or Scripts +directories, or keep them in a separate directories. We prefer to +make a directory called "buildtools" and we put this in one of our +UserStartup files: + + set Commands "{Boot}Cygnus:buildtools:,{Commands}" + +Flex uses an environment variable FLEX_SKELETON to locate its skeleton +file, so you need to do something like this, preferably in a UserStartup: + + Set FLEX_SKELETON "{Boot}"Cygnus:buildtools:Flex.skel + Export FLEX_SKELETON + +* Configuring + +Before you can build anything, you must configure. You do this by +creating an directory where object files will be stored, setdirectory +to that directory and do a configure command: + + {Boot}Cygnus:src:mpw-configure --target <name> --cc <compiler> --srcdir {Boot}Cygnus:src: --prefix <whatever> + +If the source directory is not in your {Commands} list, then you must +supply a full pathname to mpw-configure, since mpw-configure invokes +itself after switching into each subdirectory. Using a relative +pathname, even something like ':mpw-configure', will therefore not work. + +<name> must be a known target. Valid ones include "m68k-apple-macos", +"powerpc-apple-macos", "i386-unknown-go32", "mips-idt-ecoff", and +"sh-hitachi-hms". Not all target types are accepted for all of the +tools yet. + +<compiler> must be the name of the compiler to use. It defaults to "mpwc". + + (m68k) + mpwc MPW C + sc68k Symantec C + mwc68k Metrowerks C (Codewarrior) + gcc68k GCC + + (powerpc) + ppcc PPCC + mrc Macintosh on RisC (Mister C, aka(?) Frankenstein) + scppc Symantec C + mwcppc Metrowerks C (Codewarrior) + gccppc GCC + +Not all compilers will compile all tools equally well! For m68k Macs, +MPW C has the best record so far (it has problems, but they can be +worked around), while for PowerMacs, CodeWarrior is the only compiler +that has successfully compiled everything into running code. + +<prefix> is the path that "gcc" will prepend when looking for tools +to execute. GCC_EXEC_PREFIX overrides this value, so you need not +include it if you plan to use GCC_EXEC_PREFIX. + +As an example, here is the configure line that you could use to build +native PowerMac GCC: + +"{Boot}"Cygnus:src:mpw-configure --cc mwcppc --target powerpc-apple-macos --srcdir "{Boot}"Cygnus:src: --prefix "{Boot}"GNUTools: + +* Building + +If you use CodeWarrior, you *must* first set MWCIncludes to +{CIncludes}. This is because you will be building MPW tools, and +their standard I/O works by making references to data that is part of +the MPW Shell, which means that the code must be compiled and linked +with macros that refer to that data, and those macros are in +{CIncludes}, not the default {MWCIncludes}. Without this change, you +will encounter problems compiling libiberty/mpw.c, but tweaking that +file only masks the real problem, and does not fix it. + +The command + + mpw-build + +will build everything. Building will take over an hour on a Quadra 800 +or PowerMac 8100/110, longer if the sources are on a shared volume. + +You may see some warnings; these are mostly likely benign, typically +disagreements about declarations of library and system functions. + +* Installing + +To install the just-built tools, use the command + + mpw-build install + +This part of the installation procedure just copies files to the +location specified at configure time by <prefix>, and, in some cases, +renames them from temporary internal names to their usual names. This +install process is *not* the same as what the Install script does; +Install can copy tools from the installation location chosen at +configuration time to a user-chosen place, and sets up a UserStartup +file. Note that while the Install script is optional, the install +build action performs some tasks would be very hard to replicate +manually, so you should always do it before using the tools. + +* Known Problems With Using Various Compilers to Build + +Most versions of MPW C have problems with compiling GNU software. + +MPW C 3.2.x has preprocessing bugs that render it incapable of +compiling the BFD library, so it can't be used at all for building BFD. + +MPW C 3.3, 3.3.1, and 3.3.2 will spontaneously claim to have found +errors in the source code, but in fact the code is perfectly fine. If +this happens, just set the working directory back to the top-level +objdir (where the configure command above was performed), and type +"mpw-build all" again. If it goes on through the supposed error, then +you got one of the spurious errors. A full build may require a number +of these restarts. + +MPW C 3.3.3 seems to work OK, at least with the aid of a number of +workarounds that are in the sources (look for #ifdef MPW_C). + +Versions of MPW Make earlier than 4.0d2 have exhibited bizarre behavior, +failure to substitute variables and the like. + +Metrowerks CW6 PPC linker (MWLinkPPC) seems to do bad things with memory +if the "Modern Memory Manager" is turned on (in the Memory control panel), +but works OK if it is turned off. + +Metrowerks CW6 loses bigtime compiling opcodes:ppc-opc.c, which has +some deeply nested macros. (CW7 is OK.) There is a way to patch the +file, by substituting constant values. If you need to do this, +contact shebs@cygnus.com for details. + +<Gestalt.h> is missing from {CIncludes} in the MPW version that comes +with CW7. You can just copy the one in CW7's {MWCIncludes}. + +CW8 and later have changes to headers and such that will require changes +to the source in order to be able to use them to rebuild. + +KNOWN BUGS + +The declarations for memcpy and memcmp in some versions of header files +may conflict with GCC's builtin definition. Either use -fno-builtin +or ignore the warnings. + +This is not a bug, but - watch out for cr/nl translation! For instance, +if config/mpw-mh-mpw is not properly translated because it has been +copied or updated separately, then everything will almost build, but +you will get puzzling error messages from make or the compiler. + +'/' or ' ' embedded in any device, directory, or file name may or may +not work. + +objcopy -O srec foo.o makes random output filenames. + +Mac-x-mips requires -mgas but Unix hosts don't. + +GDB will frequently require a '/' on the front of a device name in order +to recognize it as an absolute rather than a relative pathname. + +GDB doesn't seem to use the printer port correctly, although it tries. + +The cursor doesn't always spin as much as it should. To get elaborate +statistics and warnings about spin rates, add this to UserStartup: + + set MEASURE_SPIN all + export MEASURE_SPIN |