/**************************************************************************
*  Copyright (C) 1993 - see 'license.doc' for complete information.       *
**************************************************************************/


Note: This document handles the specifics of compiling and running CircleMUD
      on an Amiga computer. Please read the documents in the lib/text directory
      for general information.


System Requirements
-------------------

o An Amiga computer (obviously) with a minimum 1.5Mb free RAM if you're
  running minimised. Although a 68000 CPU can do the job, for real
  multi-user action you should at least have a 68030 CPU to get good
  reponse. 
  The executable takes about 480 Kb, and data will gobble up about 1200 Kb
  for the complete standard world. 
o Kickstart 37.0 and up (OS 2.04)
o A minimum of 10 Mb if you're planning to compile/develop yourself, 
  besides playing.

Installation
------------

(read also the lib/text/running.doc for detailed info!)
The current archive contains no executables for CircleMUD proper, so you have
to take some effort and compile CircleMUD. I have included a makefile for
use with SAS/C, by changing the compiler SC into CC or GCC you should be
able to compile and link right away.
If you've trouble doing this, or you don't have a C-compiler then read the
part on the bottom of this document about obtaining executables/updates.
You might have to play a bit with your compiler options to get good code.
For instance, make sure you declare data & code as FAR, make sure that you use 
32-bit references to function pointers and if possible set stackextend ON (if 
not you have to specify a stack of about 100K before running Circle). 
Oh yes, and if you're compiling for a standard 68000 CPU with SAS/C, do not use 
the so-called utility library: it generates 68020 statements which
will cause your computer to core-dump (hehhe, that'll be cool!).
I have succesfully run Circle executables compiled for 68030/68882(FPU) and
68000/standard math functions, both under OS 2.04 and OS 3.1

Let's assume you've succesfully created the executables. You'll need to
make an assignment to the main CircleMUD directory, for example:

ASSIGN CIRCLE: DH1:Multi-User/Virtual-Worlds/Circle

Now make sure that in the root-directory of the device you installed Circle
on you create a file called HOSTS in directory ETC. File HOSTS consist of
one line with an IP-number and -address:

a.b.c.d     subdomain.subdomain.subdomain.domain

where a, b, c and d are numbers and (sub)domain text corresponding with the
domains you're connected to. But since you're not on the Internet, use your
imagination. For example DH1:ETC/HOSTS will type:

7.77.77.7       JALABBS.Arnhem.NL.Earth


To test change to the CIRCLE: directory and enter:

STACK 100000                 (only if not compiled with stackextend)
/BIN/CIRCLE

After a while CircleMUD responds with 'Entering game loop'. You're almost
ready to run now. Now start the bin/Telnet program and you're up and
running.

Since CircleMUD is fully multi-user capable, you might consider it
installing in a BBS-environment. That is possible. To do so you must create
an entry somewhere on your BBS that calls the bin/Telnet program. Telnet
offers some command parameters that will let you control the way it's
behaving in your BBS-environment:

TELNET [TIME <time-limit>] [BBS PORT <portname>]

TIME <time-limit> enables you to set a limit on the total time (in minutes) 
that a user has available to play around on your BBS. A good choice is the 
session-time still available to a user. Telnet will substract 5 minutes
from that amount and then checks if the user has 10 minutes or more left.
If so, the user is granted access to the mud, else it is refused.
For example: TELNET TIME=%TLCALL if you're using a DLG BBS/OS system. Most
other BBS-system also have an identifier that reflects the current time
left to the user. 

BBS PORT <portname> is an extension only available when you're calling
Telnet from the DLG BBS/OS system. <portname> should be replaced by the %UPORT 
expression. This enables Telnet to do some magic on the bbsport (for example
disabling CTRL-S/Q). 
The entry on my system (DLG) is:   CIRCLE:BIN/Telnet TIME=%TLCALL BBS PORT=%UPORT


Maintenance
-----------

(see also detailed information in /lib/text/Running.DOC)
I have included a small startup-script named STARTMUD that you should use
when you're setting the game up for use on a BBS. It takes care of starting
CircleMUD, maintenance on the logfiles and reboots. Of course, change the 
CIRCLE: assignment in one of the first lines to reflect your own set-up.
If you don't have a fgrep or grep utility find one or remove the specific
lines. The MV and RM commands are just the Unix equivalents of the MOVE and
DELETE command. Either use these or create a logical link between MV and
MOVE, and RM and DELETE (see your AmigaDOS manual).
If you want to use MOVE and DELETE, you must also change the source in MODIFY.C
and replace the system() calls to MV and RM by MOVE and DELETE respectively.

On my system, STARTMUD is being executed as part of the BBS-startup script
(runback >NULL: <NULL: Execute mypath:StartMUD).



Differences original CircleMUD and the Amiga version
----------------------------------------------------

The main difference is that the Amiga version operates through messageports
where the original CircleMUD uses network sockets to communicate through.
The messageports on the Amiga version connect locally with client-processes
(Telnet) that are being executed and direct all data to and from the appropiate
clients. The Telnet-client is completely based upon standard I/O so it can 
be called from a shell window or spawned by for instance a front-end program 
like a BBS.

Furthermore, all signal-trapping has been removed from the original source
since the Amiga system doesn't use signals in the same way as Unix does
(the SIGHUP etc.) to communicate with tasks and 2) it all worked fine
without them :)

The major code changes have been taken place in the COMM.C and SIGNAL.C
sources, and of course in the creation of a solid emulation library for the
Unix functions used. Bye the way, I was helped greatly by taking the
functions written by E.T. van Roode as a start. He wrote some routines 
to generally do the same thing for the Amiga LPMud version as I now use 
for CircleMUD. Credit where credit is due.
The AMIUNIX.LIB linklibrary is the result of modifications in E.T. van
Roode's routines and coding on my part. The file AMIUNIX_PROTOS.H is
sufficient to #include if you're ever thinking on extending code that will
use the Unix functions listed in the library or if you need specific
socket/Unix related structures or defines.

The Amiga CircleMUD archive includes two executables: TOUCH and TELNET.
Both are compiled for standard 68000 Amiga's.

Obtaining executables/updates
-----------------------------

New releases of Amiga CircleMUD (following the releases of the original
CircleMUD) will be available both through the Internet and my BBS.
On the Internet, use anonymous FTP to collect the archive from

ftp.cs.jhu.edu           /pub/CircleMUD

If you don't have access to Internet then you can get the executables/
new releases on my BBS:  JALABBS Amiga/Science Park Arnhem - NL
                         2:283/604.0   (Fidonet)
                         39:157/201.0  (Aminet)
                         Phone: (+31) 85 517081

Either login and download or F'req them if you're able (preferred).
As soon as updates/new releases are available of the Amiga CircleMUD source
they are also available for F'req. A list of magic names (use them to
F'req):

    Magic name                  Description
    ----------                  -----------
    CIRCLE                      The latest CircleMUD distribution kit 
                                (sources, lib, Telnet) for Amiga. You
                                *NEED* this file for all datafiles and
                                documents.
    CIRC_030                    The Circle and utilities executables
                                compiled for 68030 with coprocessor.
    CIRC_000                    The Circle and utilities executables
                                compiler for 68000 with standard math.
    TELNET                      The latest Telnet release (executables)

F'reqs are disabled on my system between 03:00 and 05:00 CET (GMT +1).
It might be possible that a local BBS-system also has these files (I'll try
to get CircleMUD distributed through the ADS/SAN/SKY/AMI network) so check
out your local systems first (much cheaper for you!).

Bugreports
----------

If (when) you ever notice anything peculiar about the way Circle is
behaving, or if you encounter serious bugs in the Amiga version, please let
me know. You can reach me by E-mail:

         J.J.M.Riethoven@cabo.agro.nl          (Internet)
         Jean-Jack Riethoven@2:283/604.999     (Fidonet)
         Jean-Jack Riethoven@39:157/201.999    (Amiganet)

The first address is the preferred address; you'll get the fastest answer.

Credits
-------

+ The [Diku] team for programming the first Dikumud. See the file CREDITS
  for all their names!
+ Jeremy Elson for enhancing Diku and making it the best MUD system around
  (IMHO) and for the quick replies on my E-mails :^)
+ E.T. van Roode for the emulation functions I used as a start to begin
  porting CircleMUD.
+ My brother Remko for programming the TOUCH util (see bin directory). His
  first C-excercise ever, being a real assembly-wiz. Furthermore thanks for
  the moral support and testing (thanks also Pablo, my youngest brother).
+ My Amiga computers... well. no words needed :-]
+ Eric de Jong (Digital Desert BBS) and Wim Rumping (Red Dwarf BBS) for
  testing the first versions.


Let the games begin!

Jean-Jack Riethoven (aka Pug)
Riethoven@cabo.agro.nl
Sat Oct 16 17:34:28 1993

Flames > NIL: