Initial revision

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