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.

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.

* Automated Installation

The simplest way to install GNU tools is to run the Install script
that should be in the same directory as this file.  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 the UserStartup in your MPW folder.

* Manual Installation

If you don't want to run the Install script, you can do installation
manually; this section describes the steps that you must do.`

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 built and installed 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

When native GCC is built using itself, it uses 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 do this 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 GCC

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

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.  For the
example above, 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 an SH-targeting GCC will produce COFF
executables.

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'.

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

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 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 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
        }
};

* 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 to Rebuild

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
	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 our
UserStartup:

	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 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 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, and

	mpw-build install

will install it.  Building will take over an hour on a Quadra 800
or PowerMac 8100/110.

You may see some warnings; these are mostly likely benign, typically
disagreements about declarations of library and system functions.

* Known Problems With Using Various Compilers to Rebuild

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