
COMPILING AND RUNNING MudOS ON THE AMIGA
========================================


1. Motivation
   ~~~~~~~~~~
   When `my' MUD switched from Amylaar to MudOS, I searched for a native MudOS
   driver for the Amiga. I found one, but had to conclude it did not work
   because:

   - the `ready to run' files on ftp.imaginary.com did not work with any
     standard MudOS-mudlib (not Nightmare, not Lima and not TMI-2);
   - the binaries were compiled using an too old release of v21; and
   - my mud had a package installed which is of course not available when
     you run those drivers.

   So I had to compile my own driver. It proved to be a major hassle to
   do this natively using SAS/C, since the SMakefile is old and lacks
   entries where a program called edit_source is compiled and run. At that
   time I wanted something up and running quickly, so I decided to try and
   compile the driver using gcc. Over time, I have been slowly adding SAS/C
   support to a (little dated, now) v22b22 source tree; the patches will be
   released when I finish this job. Expect it RSN.



2. Hardware Requirements
   ~~~~~~~~~~~~~~~~~~~~~
   I am aware that gcc is not very popular on the Amiga due to its demand
   for memory and processor power. However, it is perfect for a job such as
   this: MudOS is a Unix-program pur sang and no compiler can handle Unix-code
   better than gcc can. And you _do_ want to have a working driver, don't you?

==>   If you are the lucky user (or owner) of a (Unix)-machine which allows
==>   for cross-compilation, see Chapter 7.

   2.1 Compilation

   0 - 7 MB:    forget it. It might be possible to compile the driver on a
                machine with 6 or even 5 MB of memory, but this is machosism
                at its best.
       8 MB:    Minimum recommended amount. Compilation without optimisation
                is possible; the smaller files can be compiled with level 1
                optimisation.
 12 - 14 MB:    Full optimisation level 1 compile. (I have used 14 MB for
                quite a long time, but I think 12 MB suffices for this job.)
      20 MB:    Full optimisation level 2 compile.
      32 MB:    Full optimisation level 3 compile. (I estimate 26 - 28 MB to
                be the lowest possible amount necessary for -O3.)

      You can see, the more memory the better. Please keep in mind that
      having lots of tools running will use up memory too.

   As for the CPU, I guess any CPU will do fine. I would not use a 68000
   for compiling, though ;)). A 68030 at 25 MHz will take about 75 minutes
   for a full recompile including configuration and without optimisation; a
   68060 at 50 MHz will take an estimated 15 minutes.

   Hard disk space is also a thing to consider. Count on 15 MB for the GNU
   system at least. The sources for MudOS are about 3 MB. You need
   the same amount to compile the driver. Mudlibs like Nightmare take 6 MB in
   their basic distribution form. All in all: 25 MB of free space on your
   hard disk.

   I'd nearly forget the Kickstart. Anything from 2.04 and up will do
   (v37 and higher). gcc does not support 1.x anymore; unless you own an Amiga
   1000 I strongly urge you to upgrade to something more modern.


   2.2 Running the Driver

   The amount of memory required for running the driver depends on:

   - the size of your driver;
   - your mudlib; and
   - the memory required for your TCP/IP program.

   In addition, the driver requires two gcc-libraries: ixemul and ixnet.
   I'll get to those in a moment. I lose about 4 MB of RAM to all these
   items when I start up the driver. After that it really depends on the
   amount of rooms, objects and players loaded simultaneously. Developers 
   can cut a few corners here and there, and get away with 3 or 4 Meg. For
   serious gaming, I would triple that amount at least.

   The CPU is once again not important. Running MudOS on a 68000 requires
   patience. A lot of patience. A 68030 gives a very usuable system. Not
   at lightning speed, but there's no annoying delays either. It feels like
   a 'normal' mud. For a serious site, I would use a 68040, but keep in
   mind that the most likely bottleneck is network speed. Go for
   network speed before RAM before CPU power!

   Hard disk space is not much of a problem, unless you plan on making
   very large areas with lots of things in them. Even then, 10 MB can
   last a very long time.



3. Software Requirements
   ~~~~~~~~~~~~~~~~~~~~~

   3.1 Compiler

   I used the Geek Gadgets distribution of the GNU system found on
   ftp.ninemoons.com or one of its mirrors (ftp.uni-erlangen.de,
   ftp.grolier.fr, ...). The files you require are in
   /pub/ade/current/amiga-bin/. The Erlangen site needs /pub/amiga/ade/.. .

            DO _NOT_ USE THE ARCHIVES FOUND ON THE AMINET!!

   Alternatively, you can buy the Geek Gadgets 2 CD, which comes with the
   complete binary tree. Not only does it save you a tremendous amount on
   your phone bill, it saves many valuable MB's of hard disk space as well.
   (This can really become a problem, because the distribution is not _that_
   cleverly organised. A ZIP of a JAZ can be very helpful here.)

   Please note that in the table below, the version numbers may differ
   slightly from what you will find in the Geek Gadgets tree.

   I needed:  GG-misc-bin.lha          for: setting up GG (!!!)
              bison-1.25-bin.lha            bison
              binutils-2.7-bin.lha          as, ld
              fifo-38.4-bin.lha             use unknown
              fileutils-3.1.5-bin.lha       cp, install, mv, rm, rmdir, touch
              gcc-2.7.2.1-bin.lha           only the C-compiler
              grep-2.0-bin.lha              grep
              ixemul-47.0-bin.lha           ixemul and ixnet.library, ixprefs
              ixemul-47.0-inc-bin.lha       includes
              ixemul-47.0-env-bin.lha       environmental vars (timezones, ...)
              libm-5.4-bin.lha              math libraries
              make-3.75-bin.lha             make
              pdksh-4.9-bin.lha             sh, ksh
              sed-2.05-bin.lha              sed
              textutils-1.22-bin.lha        cat, echo

   You must obtain GG-misc-bin, since it provides the directory structure
   of the Geek Gadgets distribution. Don't get all depressed because of the size
   of these archives, you can delete a lot when you're installing them.

   Some commands (like install, echo and grep) may already be present on
   your system because they are system commands, or have already been
   provided by other compilers. You must use the GG commands; this
   automatically happens if you use the GG-shell (k)sh.

   The version numbers do not really matter, but try real hard to always get
   the lastest versions of ixemul and ixnet.library. Also, the minimum release
   for ixemul and ixnet is 43.0, because that is the version when ixnet was
   introduced.

   You do *not* need the development package of your TCP/IP-program with
   this setup.

   I did not include a diff program in the list. If you intend to
   `follow' the development of MudOS, get one from the sites mentioned above.
   This will save you hours of downloading the latest complete release of the
   sources (diffs usually being quite small).


   3.2 MudOS Sources

   I always try to use the latest _beta_ release of MudOS -- alphas contain to
   many bugs and it is not always clear whether the fault lies with the
   Amiga or with the sources. You can obtain the latest beta by ftp-ing
   beta.tar.gz from ftp.imaginary.com/pub/LPC/servers/MudOS.

   Alternatively, get a complete archive which houses both a mudlib and the
   driver sources.


   3.3 Mudlib

   You're on your own here, I'm afraid. I did not test the resulting
   drivers with Nightmare, Lima or TMI-2, but since `my' mudlib worked
   ok, I don't see why those mudlibs should fail to function. Make sure
   it's a mudlib for MudOS -- `2.4.5' and TubMud won't work, for example.
   See also 3.2.


   3.4 TCP/IP Package

   ixnet.library has the advantage of being able to work with both AmiTCP   
   and AS225, without requiring drivers specifically compiled for either one.
   One version of the driver will work happily with both network programs.
   Configuration is done at a click of the mouse. I only have AmiTCP (4.0
   demo), but I see no reason why AS225 should not work.

   I do not know whether Miami works with the driver. On the CD I had in my
   hands at a computer fair it was mentioned that Miami and AmiTCP have a nearly
   equivalent API; this means that ixnet.library can not see the difference
   between the two, and therefore happily use either one. Feedback is welcome.

   MudOS requires TCP/IP, I'm afraid. So if you don't have a program which
   extends your Amiga with TCP/IP, you can't run MudOS. (I have had too little
   feedback to justify writing a TCP/IP-less driver, and with everybody
   turning to the Internet, TCP/IP is as common as dirt these days.)


   3.5 Additional utilities

   If you have lots of memory, I strongly recommend you install a disk-caching
   program. I use `DynamiCache', which was included with my SCSI-controller.
   There are a few programs like this found on the Aminet. Alternatively, try
   phase5's site: ftp.phase5.de/pub/phase5/scsi/scsi_2.4.DMS.

   If you have a 68040 or 68060 in your Amiga, I suggest you get Kriton
   Kyrimis' libFPSP-package. It extends gcc with Motorola's own library to
   replace the FPU functions which are not supported in hardware by these
   FPUs. The small archive is not present on the Geek Gadgets CD; it is
   located in the /pub/ade/alpha/misc directory. Follow the instructions in
   its accompanying manual to install the package.

   After a bit of trouble with the plain libm-package, I have come to distrust
   it a little. If you feel like a challenge, obtain fdlibm-5.2-src.tgz from
   /pub/ade/current/amiga-src and build a new set of math libraries. I have
   never used fdlibm, but rumour has it that fdlibm might fix a few obscure
   bugs in libm. It is definitely faster too. It has not been officially
   tested, though...



4. Compiling the Driver
   ~~~~~~~~~~~~~~~~~~~~

   4.1 Introduction

   The general idea is to trick MudOS into thinking it runs on a Unix
   system (with BSD-style networking), while in reality all Unix-specific
   system and network calls are executed by appropriate functions in the
   ixemul and ixnet libraries. That means that every file name which is
   'hard coded' in the driver should be written à la Unix, so instead
   of

       Work:Games/LPmud/MudOS

   you must write

       /Work/Games/LPmud/MudOS

   In other words: <name>: is replaced by /<name>/. ixemul is able to cope
   with both naming conventions simultaneously, but MudOS is not. However,
   there are only two or three such occurences, all in configuration files --
   so it's no big deal. The file system `within' the mud is a straight copy
   from Unix anyway.

   The second side effect of that trickery is that you must UNdefine
   anything that has to do with the Amiga, how paradoxical that may seem.
   This is done with one argument on the command line of gcc, so that's not
   a big deal either.


   4.2 Patching various files

   I assume you have setup the ADE distribution without changes to the
   location of all the files. Whenever I refer to ade:bin, insert the
   directory of your GNU binaries here.

   4.2.1 build.MudOS
   First make a copy of the file, and rename the original. When you mess
   up, you always have a backup. Start up your favourite editor, and change
   the following things :

   - on line number 26, uncomment MAKE=make by removing the '#'
   - from line 134 onward, comment the entire check for make and
     how to invoke it by putting '#' in front of every line. For some
     reason, build.MudOS does not recognize the GNU distribution here.
     Then, between the last (commented) fi and the first '#' of the check 
     for CC enter:

             MAKEFILE=GNUmakefile
             echo MAKE=$MAKE >Makefile.tmp

   4.2.2 arch.h
   The sources do not detect the Amiga correctly. This is about the only place
   where we _do_ want the compiler to make use of the fact we are running on
   an Amiga. Change the detection (which is near the bottom of the file) to
   read:

       #if !defined(ARCH) && defined(MCH_AMIGA)
       #define ARCH "AmigaOS/m68k"
       #endif

   Personally, I think the m68k-suffix looks utterly cool, especially if you
   can later on truthfully change it to PPC :-).

   4.2.3 Makefile.master
   There is a slight bug in the Makefile.master file which plays up when the
   target `configure.h' is generated. There are two ways to deal with this
   bug: the decent and the not-so-decent method. Both work, but I recommend
   you use the decent version.

   Decent method    Load Makefile.master, and search for the target
   ~~~~~~~~~~~~~    configure.h. Look at the part which starts with `if test'
   and locate the first `fi'. In front of the latter, place `else true;'. Save
   the file, but make sure that the tabs are not expanded into spaces. GoldED
   has this annoying habit, but you can force tab-saving by enabling `save
   tabs' in Config/Misc/Files (GoldED 3) or Extras/Options Local/Misc (GoldED
   4). If you don't do this, make will play up.

   Not-so-decent method   Locate the same `if test' outlined in the previous
   ~~~~~~~~~~~~~~~~~~~~   paragraph, but add a `-' directly in front of that
   if. Save in the same way as was explained above.

   4.2.4 Making MudOS use stdout instead of stderr
   MudOS is real Unix program and will therefore make use of the
   standard-error stream (also known as stderr) to relay error messages to
   you. Unfortunately, none of the native shells (shell, ZShell) supports
   stderr. That means you cannot redirect the error messages to a file. GG's
   (k)sh of course knows about stderr, but many people will be put off by this
   particular shell. Fortunately, it is very easy to patch the sources so they
   use st(andar)dout(put) instead. Cut out the following script, and execute
   it from within sh.

   #!/bin/sh
   grep -l stderr *.c >stderr.list
   grep -l stderr *.h >>stderr.list
   grep -l stderr packages/* >>stderr.list
   grep -l stderr mudlib/* >>stderr.list
   for FILE in `cat stderr.list`; do \
       sed s/stderr/stdout/g $FILE >$FILE.new; \
       mv $FILE $FILE.old; \
       mv $FILE.new $FILE; \
   done;
   rm stderr.list

   Every file containing the word `stderr' will be backed up to <file>.old;
   the new file will have every stderr replaced by stdout. Mind: the option
   NONINTERACTIVE_STDERR_WRITE in options.h has _not_ changed, but it _will_
   use stdout instead of stderr!

   4.2.5 Making MudOS recognize the FPSP-library (68040+ users only)
   If you want to have MudOS recognize the installed FPSP-library, load
   edit_source.c and locate the line

        check_library("-lm");

   Insert the line

        check_library("-lFPSP");

   BEFORE the line where the check for -lm is initiated.


   4.3 Running build.MudOS and configuring the GNUmakefile

   Run ade:bin/sh, change to the directory where your build file resides (if
   it is in PR:MudOS/, type cd /PR/MudOS -- Unix style ;) ), and type

        build.MudOS

   build.MudOS will now try and locate all kinds of programs and find out
   how to invoke them. (You can pass various options to build.MudOS to turn
   the driver into a debugging or developmental driver, but the former blows
   up the program to 2.5 MB at least, and the latter is not very useful unless
   you have a very fast Amiga. I will silently assume you are just interested
   in getting MudOS to run on your own computer for now :-).) Ignore all
   errors. When the script has finished executing, it should print some
   information on how the GNUmakefile will start gcc. Leave the crummy shell
   sh by typing exit, and study the GNUmakefile. You will probably need to
   change a few entries. Here are some helpful hints:

   - INSTALL_DIR needs to point to a valid directory if you plan on using the
     `install' target of the GNUmakefile. Since this involves a copy of just
     three files (of which you really require only one), I usually leave this
     unaltered and do the copying by hand.
   - OPTIMIZE is for the power users amongst us. If you can spare the memory,
     I definitely recommend you insert `-O2 -fno-strength-reduce
     -fomit-frame-pointer' here. gcc knows what optimising is all about and
     will do a good job if you let it. Users with little memory can insert
     `-O1', or simply leave the field open. See paragraph 2.1.
   - CFLAGS is something you _must_ change. For one thing, it should ALWAYS
     have an option -UAMIGA somewhere. This disables the few remaining parts
     in the sources which are Amiga-only. Then, insert your preferred CPU
     options here. 68040+FPSP-users: take care you do NOT include a -m68881
     option along with -m68040 ; this is a sure way to embark on a one-way
     trip to lovely India when you run the driver! You can also include an
     option to switch the compiler into verbose mode (-v), or to turn compiler
     warnings on (-Wall). If you insist on compiling a debugging or
     developmental driver, have build.MudOS provide you with the necessary
     options and then round up by making your own modifications.

   You do not need to change anything else. When you save the file, make sure
   tabs are saved as tabs!


   4.4 Configuring options.h

   This file configures the driver at compile-time. I can't tell you how
   to set all options, but there are a few I'd like to mention:

   - define SYSMALLOC or SMALLOC for memory management; gcc does not
     support BSDMALLOC due to a lack of sbrk() (so do not define SBRK_OK);
   - take care with NONINTERACTIVE_STDERR_WRITE if you have applied the
     stderr->stdout patch.
   - CONFIG_FILE_DIR should be written à la Unix; you can remove the
     check for LATTICE, since it is obsolete.
   - the run-time loading of LPC->C compiled code does not work on the
     Amiga. So undef RUNTIME_LOADING. I think the LPC->C compiler works,
     since I can't think of any reason why it shouldn't. However, the code it
     produces it not particularly good and it still requires you to stop the
     driver in order to use it. Far too much trouble, IMO.
   - any code which makes use of fork() (in the standard driver
     sources, this is the EXTERNAL package only) cannot be run on the Amiga
     without severe modifications. This is because fork() creates a second
     process, which is _exactly_ the same as the one which called fork(): even
     the memory locations where all the code and the data are stored are
     equal. This cannot be achieved without a VM-supporting kernel. Alas! (Of
     course, one could rewrite packages/external.c to use SystemTags() or
     CreateNewProc() since they provide ample support for spawning off
     children. Volunteers, step forward.)


   4.5 Actual Compiling

   If you have little memory (say, 6 Mb or less), I'd advise you to reboot
   with the smallest possible startup-sequences and assign T: to a hard disk
   before you execute the GG-startup script. IF THE COMPILER CRASHES, YOU MAY
   END UP WITH A CORRUPTED HARD DRIVE. I take *NO* responsibility if anything
   goes wrong. If you have a caching program, put the buffer to around 8
   MB for maximum effect. (I use 10 MB and get a hit rate of about 92%). Type

        make all

   Now wait and watch. First, make will build a program called edit_source
   and execute it. edit_source will invoke the gcc compiler at least 20
   times to build a configuration file. This only needs to be done once.
   After that, the driver is compiled. If you have little memory, watch
   especially carefully if the compiler is busy with

   - grammar.tab.c
   - interpret.c (the biggest troublemaker)
   - object.c
   - efuns_main.c
   - linking

   If the compiler exits (due to a lack of 'virtual memory'), you must try
   and compile such a file by hand. Start up with an ABSOLUTE MINIMUM of
   programs, assigns, devices, ... in your startup files and issue (after
   executing the ADE-startup)

        cd <MudOS-sources directory>
        gcc -UAMIGA -m68... -v -Wall -o obj/<file>.o -c <file>.c

   gcc can't use less memory when compiling like this. So if this fails,
   you're stuck. With interpret.c I estimate memory usage at 3.8 or 3.9
   Mb -- so 4 Mb internal memory is *really* very tight. 

   If you want to compile with as much optimisation as possible, turn
   on the required level of optimization in the GNUmakefile and run

        make files

   first. Then compile the problem files without optimization by hand
   by typing the above line and finish by

        make main_build

   Please notice the `obj/' prefix on this command line. make defines a
   variable called OBJDIR where all object files are stored. This keeps
   your source directory relatively clean. The makefile is built in such
   a way that both make and gcc will always look in that directory first
   when compiling or linking. If you do not store your compiled-by-hand
   programs there, make will notice no object file exists, and happily
   instruct gcc to make a new one -- probably using all the wrong options.

   After an hour on a moderately fast system, gcc will enter the linking
   stage. If this fails due to a lack of memory, you're stuck. Plain and
   simple. All files need to be loaded into memory to resolve all references.
   
   If linking is succesful, you are now the proud owner of an  executable
   MudOS driver. make is not done yet, however. It will now build and compile
   two small program called `addr_server' and `portbind' (if you use a driver
   with a version number of -I think- v22.1b1 or later). Then the compiling is
   finished.

   Move the driver executable (called `driver' unless you gave it a
   different name in the makefile) and the two programs to your mud binaries
   directory.



5. Running the Driver
   ~~~~~~~~~~~~~~~~~~

   5.1 Configuring the Run-Time Options

   Get out the *.config file, and edit `mudlib directory' and `binary
   directory' to Unix-style directory names. For example:

      Work:Games/LPmud/bin (alias MUDBIN:)

   is entered as

      /Work/Games/LPmud/bin     or     /MUDBIN

   Strictly, the capitals are not necessary, since AmigaDOS eventually
   ignores them, but it shows good Unix style to keep them anyway.

   Take a look at `time to swap' -- small machines with little
   memory may need a small value here.

   The rest of the values is up to you.

   Finally, run the ixprefs program and enter the networking package you
   have. I also have `translate /', `case sensitive pattern matching' and
   `suppression of the requester' checked, but I don't have a clue as to
   whether they are really necessary.


   5.2 And Really Finally, Running the Driver

   Running your driver requires three steps:

   - start your TCP/IP program, and make sure it is `online', i.e. ready
     to be used by other programs. It does *not* mean you must have a
     open telephone line to your Internet provider, though if you have,
     people from outside can log in on your mud.
   - increase the stack to 16384, and start the addr_server program
     with one option: a port number. This number must be the same as the
     one defined in the run-time configuration file.
   - increase the stack to 98304, and start the driver with at least one
     option: the name of the configuration file. I don't know whether
     98304 bytes is enough, but you surely needn't to use more than
     twice this amount. I run my mud with a few very complex rooms and
     objects on 98304 bytes.

   Unless you have applied the stderr->stdout patch, you `loose' a shell
   window to the driver (again, unless you are using (k)sh). The advantage is
   that you can now simply shut down the driver by pressing CTRL-C in that
   window. (Sending a `c' break signal to the driver process will do the
   same.) Otherwise you can simply redirect the output by issuing a command
   like

        MudOS runtime.config >nil: <nil:

   MudOS supports more command-line parameters, which I never use. They are
   documented in the docs of MudOS v21; you'll have to rummage around
   ftp.imaginary.com a bit in order to find them.

   The last step is the nerve-wracking one. If all goes well, you should
   receive a message that the driver accepts connections on a certain
   port number (which is defined in the run-time configuration file).
   Test with

        telnet localhost <port number>

   Any other regular telnets like letnet and AmTelnet (the latter
   requiring MUI 3.8) worked fine. Of the available clients, PlayMUD by Lars
   Duening did not like my setup, and refused to connect to the mud. I have a
   strong suspicion it is driver-related and thus cannot be fixed easily. On
   the other hand, Ghuiseppe Ghìbo's MUD client worked fine, but since my own
   mudlib treats things a little different than what the client expects, it
   (unfortunately) got messed up in the end. Please note that this is _not_ a
   driver problem.

   The addr_server program is not required by MudOS. If you decide to go
   economical on your memory, you can leave it out. You will then not see an
   ASCII-IP address anymore, but its numerical equivalent. portbind is for
   advanced use only, and unlikely to be of use to a home-based copy of the
   mudlib you are developing for.


   5.3 Error! Boom! Crash!

   If you receive a driver error, this is either caused by faulty LPC code
   or a bug in the driver. Make sure you install your mudlib EXACTLY as
   is told in the accompanying docs. Make sure you have compiled the driver
   with EXACTLY the same options as provided in the options.h-file.

   Still no luck? Darned... I wish it were different, but I am in no
   position to help, since I can't simply compile the driver anew and check
   with your mudlib. Besides, I only own a 68040, and though other CPU
   code will run with this chip, the 68040 can never fully imitate that
   other CPU.

   A friend of mine has used a 68000 version of the driver for quite some
   time (until he switched to a 68030), and discovered that file system
   functions would malfunction during one call for no apparent reason, and
   then work perfectly for a while again. I had discovered earlier that the
   68030-version was affected by this problem too, but less often. Whether
   this is due to our setups setup, the compiler, the ix* libraries, the
   mudlib (which is still being worked upon) neither of us knows for sure. The
   most important thing is that the driver does not GURU, and we both felt
   that a working driver is better than no driver at all, as is the case now.



6. Native Amiga MudOS driver
   ~~~~~~~~~~~~~~~~~~~~~~~~~

   When I was trying to get MudOS to work with the gcc-compiler, Anthon Pang
   (Robocoder, apang@mindlink.bc.ca) was working on a native v21.7 MudOS
   driver. I believe he abandoned the project some time ago, which is a shame,
   because his driver would support all major compilers (including Aztec!) and
   come with an option to disable TCP/IP.

   I have decided to `continue' his work, because I nearly all questions I
   received from interested people were `I want to compile the driver with
   SAS/C, but...'. Frankly, I got a bit fed up with the slow speed of gcc too.
   However, at the moment I am just concentrating on getting the thing to work
   with AmiTCP and SAS/C. Don't expect anything in terms of support for other
   TCP/IP stacks or other compilers.



7. Cross-compiling MudOS
   ~~~~~~~~~~~~~~~~~~~~~

   When you have compiled MudOS a few times, you will no doubt have noticed it
   takes _quite_ a while. If you are in the lucky possession of a faster
   machine which is supported by gcc, you can build a cross-compiler there and
   take advantage of its speed (and probably memory as well :)).
   Unfortunately, MudOS makes use of a non-standard configuration procedure
   which still requires you to perform a couple of steps on your Amiga. (This
   is not an Amiga-specific problem, by the way.) Follow the following
   procedure to create an -O3 optimised driver to run on your 6 MB A500 :).

   1. First create the cross-compiler on the host platform. You do this by
      getting a copy of the binutils and gcc sources from Ninemoons or its
      mirrors. They are stored in the directory /pub/ade/current/amiga-src and
      following the instructions. DO NOT USE OTHER SOURCES -- THEY LACK AMIGA
      SUPPORT!

      Creating a cross-compiler is a tricky job and you may have to repeat the
      procedure a few times in order to get it right. When you are building
      the set of binutils, create GNU's own linker (ld) and its own assembler
      (gas). There is no need to hassle with the hosts assembler if you are
      compiling everything anyway. Don't forget to tell the configure script
      for the new compiler it needs to use its own assembler!

      You can use the FPSP-package again, if you like. This is a very strong
      point of gcc: the library format is the same on any platform. So even if
      the host can not execute the routines it contains, it can definitely
      read them into memory and link them to an executable!

      Before I forget: compiling gcc is a computationally heavy job. Unless
      you are root on a system, always ask the system administrator first if
      you can a) use about 50 MB of extra diskspace all of a sudden and b)
      increase the load by one point for about an hour or two. In most cases,
      sysadmins love to do irregular stuff like this and will be more than
      happy to lend you a (big) helping hand. Step on their toes and you can
      kiss a fast MudOS-compile session goodbye.

   2. Unarchive the sources on your Amiga and proceed as was outlined in the
      paragraphs 4.1, 4.2, 4.3 and 4.4. However, issue

          make files

      instead of `make all' when `compiling' the driver.

   3. Copy the source tree to the host computer. Pay special attention that
      the local configuration files (configuration, configure.h, system_libs
      and options.h) are copied along. Check whether the links to the memory
      allocation and wrapper packages are still pointing to the right files
      and reinstate them if necessary.

   4. Edit the GNUmakefile to reflect your new `setup'. Change the OPTIMIZE
      entry (of course :)), but also make _very_ sure the correct binaries are
      invoked for gcc and ranlib. For example, on my Linux system, they are
      called `m68k-cbm-amigados-gcc' and `m68k-cbm-amigados-ranlib'. Don't
      forget the gcc command in the CPP entry! (The cross-compiler itself
      has been told during _its_ compilation phase where to look for ld, gas
      and the various linker libraries, so don't worry about missing entries
      for ld and gas.)

   5. Ready to go to Warp Speed? Enter

          make main_build

      and watch gcc _SCREAM_ through the sources. It is an unnerving
      experience when you are using a Pentium Pro or a heavy workstation like
      an SG Indy, I can assure you :).

   6. Depending on the Warp Factor, the driver will be ready within 5 to 10
      minutes (I always wondered how much time the Cray T3 of the university
      in Delft would take... This is a rather expensive joke, however :( ).
      Ship driver and the two auxillary programs to your Amiga and proceed
      with Chapter 5.

   7. When you are cleaning up the directory on the host, do not use

          make spotless

      but refrain yourself to

          make clean

      otherwise you will have to move over a fresh set of configuration files.

   8. Start saving for a PowerPC.



8. How to Reach Me
   ~~~~~~~~~~~~~~~

   You can reach me via e-mail on M.D.deJong@stm.tudelft.nl. Please, do
   *not* report MudOS errors to me; I did not develop the driver, I merely
   compiled the thing. However, when you have suggestions relating to better
   compilation, I'll be glad to hear from you. 


   Happing compiling and MUDding,
                        Maarten

