Porting CircleMUD
-----------------
CircleMUD should work on most UNIX platforms without any modifications;
simply run the "configure" script and it should automatically detect what
type of system you have and anything that may be strange about it. These
findings are all stored in a header file called conf.h which is created in
the src directory from a template called conf.h.in. A Makefile is also
created from the template Makefile.in.
Non-UNIX platforms are a problem. Some can't run CircleMUD at all.
However, any multitasking OS that has an ANSI C compiler, and supports
non-blocking I/O and socket-based TCP/IP networking, should theoretically
be able to run CircleMUD (e.g. OS/2, Amiga, Mac, Windows 3.11/NT/95).
The port can be very easy or very difficult, depending mainly on whether
or nor your OS supports the Berkeley socket API. Windows 95, for example,
supports Berkeley sockets with a few modifications using the WinSock
library, and OS/2 supports Berkeley sockets with no source changes at all.
The general steps for porting CircleMUD to a non-UNIX platform are listed
below. Note that I have already ported Circle to Windows 95, so if you're
confused as to how to perform some of these steps, you can look at what
I've done as an example (see the files conf.h.win, Makefile.win and
README.WIN).
Note that you should not try to do this unless you are an experienced C
programmer and have a solid, working knowledge of the system to which you
are trying to port the code.
Step 1. Create a "conf.h" file for your system. Copy the template
"conf.h.in" to "conf.h", and then define or undefine each item
as directed by the comments and based on the characteristics of
your system. To write the conf.h file, you'll need to know which
header files are included with your system, the return type of
signals, whether or not your compiler supports the 'const'
keyword, and whether or not you have various functions such as
crypt() and random().
Also, you can ignore the HAVE_LIBxxx and HAVE_xxx_PROTO constants
at the end of conf.h.in; they are not used in the code (they are
part of UNIX autoconf).
Step 2. Create a Makefile. Again, copy the template Makefile.in and make
any changes which may be appropriate for your system. Make sure
to remove the @xxx@ variables such as @LIBS@, @CC@, @NETLIB@, etc.,
and replace them with the appropriate values if necessary.
Step 3. Make the appropriate patches to the code so that the TCP/IP reads
and writes and signal handling are compatible with your system.
This is the hard part of porting Circle. All of the changes you'll
need to make will probably be in the source file comm.c.
Some tips about porting:
Making your own CIRCLE_system constant
--------------------------------------
Each system to which Circle is already ported has a CIRCLE_xx
constant associated with it: CIRCLE_UNIX for plain vanilla
UNIX CircleMUD, CIRCLE_WINDOWS for MS Win95/NT, CIRCLE_OS2 for
IBM OS/2, and CIRCLE_AMIGA for the Amiga. You must use a
similar constant for your system. At the top of your conf.h,
make sure to comment out "#define CIRCLE_UNIX" and add
"#define CIRCLE_YOUR_SYSTEM".
ANSI C and GCC
--------------
As long as your system has an ANSI C compiler, all of the code
(except for comm.c) should compile with no major complaints.
However, Circle was written with gcc, and some compilers are
nitpicky about things that gcc does not care about (and the
other way around). Therefore, you are *highly* encouraged to
use gcc if at all possible. gcc has been ported to a very
large number of platforms, possibly including yours, and your
port will be made much easier if you use gcc. You can download
gcc via anonymous FTP from ftp.gnu.ai.mit.edu:/pub/gnu.
Non-Blocking I/O
----------------
Make absolutely sure to use non-blocking I/O; i.e., make sure
to enable the option so that the read() system call will
immediately return with an error if there is no data available.
If you do *not* use non-blocking I/O, read() will "block,"
meaning it will wait infinitely for one particular player to
type something even if other players are trying to enter
commands. If your system does not implement non-blocking I/O
correctly, try using the POSIX_NONBLOCK_BROKEN constant in
sysdep.h.
Timing
------
CircleMUD needs a fairly precise (on the order of 5 or 10 ms)
timer in order to correctly schedule events such as zone
resets, point regeneration ("ticks"), corpse decomposition,
and other automatic tasks. If your system supports the
select() system call with sufficient precision, the default
timing code should work correctly. If not, you'll have to
find out which system calls your system supports for
determining how much time has passed and replace the select()
timing method.
Signals and Signal Handlers
---------------------------
A note about signals: Most systems don't support the concept of
signals in the same way that UNIX does. Since signals are not
a critical part of how Circle works anyway (they are only used
for updating the wizlist and some other trivial things), all
signal handling is turned off by default when compiling under
any non-UNIX platform (i.e., the Windows 95 and Amiga ports do
not use signals at all.) Simply make sure that CIRCLE_UNIX is
*not* defined in your conf.h file and all signal code will be
ignored automatically.
IMPORTANT: Remember to keep any changes you make surrounded by
#ifdef statements (i.e., "#ifdef CIRCLE_WINDOWS ... #endif"). If
you make absolutely sure to mark all of your changes with #ifdef
statements, then your patches (once you get them to work) will be
suitable for incorporation into the CircleMUD distribution,
meaning that CircleMUD will officially support your platform.
Step 4. Test your changes! Make sure that multiple people can log in
simultaneously and that they can all type commands at the same
time. No player should ever have a "frozen" screen just because
another is waiting at a prompt. Leave the MUD up for at least
24 hours, preferably with people playing it, to make sure that
your changes are stable. Make sure that automatic events such
as zone resets, point regeneration, and corpse decomposition are
being timed correctly (a tick should be 75 seconds). Try resetting
all the zones repeatedly by typing "zr *" many times. Play the MUD
and make sure that the basic commands (killing mobs as a mortal,
casting spells, etc.) work correctly.
Step 5. If you are satisfied that your changes work correctly, you are
encouraged to submit them to be included as part of the stock
CircleMUD distribution so that future releases of Circle will
support your platform. This prevents you from re-porting the code
every time a new version is released and allows other people who
use your platform to enjoy CircleMUD as well.
To submit your changes you must make a patch file using the
GNU 'diff' program which can be downloaded by anonymous FTP from
ftp.gnu.ai.mit.edu:/pub/gnu/diffutils-x.x.tar.gz. diff will
create a patch file which can be later used with the 'patch'
utility to incorporate your changes into the stock CircleMUD
distribution. For example, if you have a copy of stock (plain)
CircleMUD in the "stock-circle" directory, and your changes are
in "my-circle", you can create a patch file like this:
diff -u --new-file --recursive stock-circle/src my-circle/src > patch
This will create a file called 'patch' with your patches. You should
then try to use the 'patch' program (the inverse of 'diff') on a
copy of stock circle to make sure that Circle is correctly changed
to incorporate your patches.
This step is very important: if you don't create these patches
correctly, your work will be useless because no one will be able
to figure out what you did! Make sure to read the documentation to
'diff' and 'patch' if you don't understand how to use them.
If your patches work, CELEBRATE!!
Step 6. Write a README file for your operating system that describes
everything that has to be done by another user of your operating
system to get CircleMUD to compile from scratch. You should include
a section on required hardware, software, compilers, libraries, etc.
Also include detailed, step-by-step instructions on how to compile
and run everything. You can look at the other README files in the
distribution (README.WIN, README.OS2, etc.) for examples of what
your README file should include.
Step 7. You're done! Congratulations! Mail your conf.h, Makefile, patches,
and README file to Jeremy Elson (jelson@circlemud.org) so that they
can be included in future releases of CircleMUD. Please share your
work so that other users of your OS can use Circle, too.
Jeremy Elson
jelson@circlemud.org