This is the README file for TinyMUSH 2.2.
It is divided into several sections: Introduction, Compatibility,
and Installation.
--------------------------------------------------------------------------
INTRODUCTION
TinyMUSH 2.2 is an enhanced version of the TinyMUSH 2.0 server. It is
derived from TinyMUSH 2.0.10p5. Many bugs have been fixed; in
particular, all of the memory leaks should be gone, and the server
should be in highly stable condition. A number of features have been
added, as well.
When you are finished reading this file, you will also want to read
the README-2.0 file, which contains setup information. Recent changes
can be found in the CHANGES file; a changes history for TinyMUSH 2.0
can be found in CHANGES-2.0.
There are two levels of TinyMUSH 2.2 distributions. There are
"snapshots", and there are real "releases". Releases are
supported. Snapshots are not. If you use a snapshot version, you
should to have the technical competence to be able to fix your own
problems; report any bugs found, but snapshots are likely to be
unstable and could eat your database. For information on support for
TinyMUSH 2.2 releases, please see the end of this document.
Releases of TinyMUSH 2.2 are on a relatively slow schedule. Extensive
testing of the server prior to release, and a conservative approach
to feature additions, make frequent updates fairly unnecessary.
Development efforts are focused towards creating a more reliable,
more easily maintained, more efficient server.
--------------------------------------------------------------------------
COMPATIBILITY
TinyMUSH 2.2 has been successfully compiled and run in the following
environments:
SunOS 4.1.1 - 4.1.4 Solaris 5.2 - 5.5
Irix 4.0.5, 5.2, 5.3, 6.2 Dynix/PTX 2.0.4
AIX 3.2 HP-UX A.09.01
Linux 1.1.90, 1.2.11, 1.3.35 BSD/386 1.1
Ultrix 4.2 SCO Unixware 2.1
If you use it in another environment, please let us know (and also
note any changes that you had to make). An ANSI-compliant compiler is
not required, but is strongly recommended.
autoconf does still seem to have a few problems, and there are few things
which we recommend, but are not strictly necessary. After running
'configure', you will need to manually edit the Makefile and autoconf.h
on certain systems, in the following manner:
BSD/386: BSD/386's ndbm implementation is broken. Comment out the
'#define HAVE_NDBM 1' line in autoconf.h. Add, to the LIBOBJS line
in the Makefile, 'myndbm.o'.
Dynix/PTX: Add '-DTLI' to the DEFS line in the Makefile. TLI networking
is somewhat more stable, on the Sequent, which has a buggy implementation
of BSD sockets. Also, the system-default number of file descriptors is
usually something ridiculously low, such as 32. You will probably want to
raise this, since it limits the maximum number of users which can be
simultaneously connected. Add '-DNUMFDS_LIMIT=256' to the DEFS line in
the Makefile. (You may also want to change the "netmush:" rule to
"netmush:&" and do a "make -PX", where X is the number of processors,
in order to do a parallel make.)
FreeBSD: See BSD/386 above.
SCO Unixware: You need the software development kit, gcc, and GNU make.
Change the paths to point to the proper signals.h file. Comment out
the '#define NEED_SPRINTF_DCL 1' in autoconf.h
SGI Irix: If you use SGI's cc, rather than gcc, you must add '-cckr'
to the CFLAGS line in the Makefile.
Solaris: In the Makefile, add to the DEFS, '-I/usr/ucbinclude'.
Also in the Makefile, add, to the MORELIBS, '-L/usr/ucblib -lucb'.
Finally, add, to the top of mush.config, the follwing line:
LD_LIBRARY_PATH=/usr/ucblib:/usr/lib; export LD_LIBRARY_PATH
SunOS 4.1.2: You may need to comment out '#define HAVE_NDBM 1' in autoconf.h.
The 2.2 distribution splits files up over multiple directories as follows:
conf MUSH runtime configuration files.
misc Assorted extras that don't fit anywhere else.
scripts Shell scripts.
src C source to the server.
text MUSH runtime text files.
vms Support for a VMS port (not tested).
--------------------------------------------------------------------------
INSTALLATION
Setting up 2.2 is done in approximately the same way as the 2.0 setup
described in the README-2.0 file. There are, however, some changes,
so the process is summarized here.
1. Go to the top-level directory (the directory where this README file is
normally located).
2. Run 'configure' (by typing './configure'). This will customize autoconf.h
and the Makefile for your system. If you have gcc (the GNU C compiler)
installed on your system, it will automatically be selected as the
compiler of choice.
3. TinyMUSH 2.2 is set up to use some features only found in GNU make
and other newer versions of make, such as VPATH. If you do not have
GNU make, you have two options.
a) Get and install GNU make. It's small, trivial to install, and very
worthwhile. Both it and gcc are available via anonymous ftp from
prep.ai.mit.edu, in /pub/gnu.
b) Type 'make patrules'. Then, edit your Makefile. Go down to where
it says "EXTRA CONFIGURATION STUFF HERE". Follow the directions
(which basically amount to commenting out a few lines and
uncommenting one line).
4. Edit the Makefile and make any changes that might be necessary.
You might need to change any C flags needed by your particular C
compiler (in particular, -fpcc-struct-return), add whatever esoteric
libraries are needed by your system, and change the location of the
game files (the value of the GAME directory). See below for
additional notes on Makefile options.
5. Edit config.h and select the configuration options you want. The
options are documented in that file.
6. Type 'make'. This should produce netmush, mkindx, and dbconvert.
7. Briefly, if you are starting from scratch, type 'make new-install'.
Otherwise, type 'make install'. For more detail on starting from
scratch, or converting from PennMUSH, TinyMUD, or TinyMUSE, please
refer to section 4 in the README-2.0 file. If you are starting from
an existing 2.0 or 2.2 database, please see below.
8. You can 'rm *.o' to get rid of the object files, at this point, if
you need to conserve disk space.
*****
Version 2.2.4 does not have any changes in database format; if you are
upgrading from 2.2.3, you do not need to do anything special. We
highly recommend, however, that you flatfile by running a db_unload,
prior to upgrading your code version; it's always useful to have
backups, in case something goes wrong.
*****
If you are upgrading from a version of TinyMUSH 2.2 prior to 2.2.3
(from Database Version 9 or earlier), follow the sequence of steps for
converting from TinyMUSH 2.0 below, substituting, in step 1, for "your
TinyMUSH 2.0 dbconvert", "your old 2.2 dbconvert".
*****
If you are converting from a version of TinyMUSH 2.0, do the following:
1. Shut down your game. Flatfile by running a db_unload (using your
TinyMUSH 2.0 dbconvert!), and put a copy of this flatfile someplace safe.
2. Compile TinyMUSH 2.2. Move the netmush, dbconvert, and mkindx files
into the directory where you normally keep those files.
3. Remove the .db* and .gdbm* files (some operating systems seem to be
confused by the presence of an existing gdbm file, in particular).
Run a db_load on the flatfile that you made in Step 1 (using the
2.2 dbconvert).
4. Do a Startmush. The game should now be operational under 2.2.
You _must_ follow this sequence of steps; if you do not do the
db_unload and db_load, the game will probably still start, but
there will be database damage resulting from screwed-up quotas.
*****
If you are converting from a Beta Snapshot of TinyMUSH 2.2 prior to 1/16:
1. Shut down your game. Flatfile by running a db_unload, and put a copy
of this flatfile someplace safe.
2. Compile this version of TinyMUSH 2.2, adding -DBETA_QUOTAS to the
compile defines. (If you have typed quotas split up into QuotaRoom,
RQuotaroom, etc., you have Beta Quotas.) Move the netmush, dbconvert,
and mkindx files into the directory where you normally keep these files.
3. Remove the .db* and .gdbm* files (some operating systems seem to be
confused by the presence of an existing gdbm file, in particular).
Run a db_load on the flatfile that you made in Step 1.
4. Do a Startmush. The game should now be operational. It is imperative
that you follow these sequence of steps; doing otherwise will result
in database damage from screwed-up quotas.
5. At some future point in time, you will want to recompile without
the BETA_QUOTAS define.
*****
Makefile Options
There are three major options in the Makefile that you will have to
concern yourself with.
1. Attribute-level vs. Object-level Caching. Essentially, this means,
"Does the MUSH load individual attributes when it needs them, or
does it load the entire object that the needed attribute is on?"
In general, we have found object-level caching to be more efficient,
and thus recommend it.
2. RWHO. The common RWHO server for MUSHes, which allows people to
send login data to a central server, is run by Jennifer Smith,
jds@math.okstate.edu, at riemann.math.okstate.edu 6889
If you decide to turn RWHO on, contact her and she'll set
you up with a password and so forth.
3. Size of the attribute hash table. Use the defaults initially; check
'@list hash' from time to time, and look at the bottom line, which
should read 'Vattr stats: <some number> alloc, <other stuff>'.
That number is the number of user-named attributes in your database.
If possible, you want a hash table which is about the same number;
there is, however, a memory trade-off. The hash table size must
be a power of two; below is a table listing sizes and memory used.
Vattr Size Memory in K Vattr Size Memory in K
512 8 8192 128
1024 16 16384 256
2048 32 32768 512
4096 64 65536 1024
Values under the default of 16384 are not recommended unless your
database is under 5,000 objects and memory overhead is of very great
concern.
*****
Known Bugs and Problems
As of 3/31/95, TinyMUSH 2.2 has the following known problems:
- Evaluative searches cannot be done with lattr(), as both of them use
the olist-handling code.
- dbconvert utilizes the cache when converting from flatfile, and thus,
extremely large objects (those with 1000+ attributes) may cause the
dbconvert process to become extremely large.
As of 2/15/96, TinyMUSH also has the following known problem:
- dbconvert from Version 8 to Version 9 (accomodating the COMMANDS flag)
only marks the flag on objects which actually have $commands directly
set on their attributes; it does not set the flag on child objects
which only inherit $commands from their parents.
*****
Be advised that you will need, at minimum, a machine with 16 MB
of physical RAM, and at least 10 MB of disk space just for the game,
in order to grow to any reasonable size. Also, we strongly advise
you to obtain the consent of your systems administrator, before
running a MUSH on your system.
Other MUSH stuff is available on ftp.tinymush.org, in /pub/mud/tinymush.
The archive includes the MUSH Manual, various MUSHcode packages, server
patches, and other bits of useful documentation. For philosophical
reasons, TinyMUSH 2.2 does not officially support identd "authentication";
there are, however, patches available on this FTP site.
There are also two major mailing lists, tinymush-programmers@clock.org
and mushhacks@chaco.com, for the discussion of softcode and hardcode
issues, respectively. If you want to subscribe to the lists, send email
to tinymush-programmers-request@clock.org, or mushhacks-request@chaco.com,
respectively. Do NOT send "Please subscribe me" messages to the lists
themselves.
TinyMUSH 2.2 is currently supported by a group of people who can be
reached via email to 'hogs@clock.org'. When reporting bugs,
please be as specific as possible; in particular, note your TinyMUSH
revision number, the release date, your machine type, OS, and
compiler. This is not a public mailing list; it is for the
development team only.
-- The TinyMUSH 2.2 Development Team