root/releases/1.6/0p2/README

****IF YOU'VE NEVER USED A POST-PL10 PENNMUSH RELEASE, READ THIS FILE!
****INSTALLATION AND CONFIGURATION PROCEDURES HAVE CHANGED SINCE PL10!

============================================================================
                   User's Guide to PennMUSH (post-pl10) 
============================================================================

Most of this Guide was written by Amberyl, and is used with permission.
Modifications are by Paul/Javelin.

I.   Introduction
II.  Installation Guide (new users)
III. Conversion Guide (previous users) *NEW STUFF*
IV.  Additional Options
V.   Trouble-shooting
VI.  Comments

You may also want to take a look at Javelin's Guide for PennMUSH Gods,
at http://mellers1.psych.berkeley.edu/~alansz/guide.html
or by ftp from mellers1.psych.berkeley.edu, /pub/PennMUSH/Guide
============================================================================
 
I.   Introduction
 
     PennMUSH is a TinyMUD derivative, and one of the branches along the
MUSH line. "Vanilla" TinyMUSH, which added the "v" registers and functions
to the basic TinyMUD building commands, was written by Larry Foard. The
code was later expanded by Jin, of MicroMUSH. In January of 1991, MicroMUSH
changed its name to MicroMUSE, and the code there continued to develop
under the MUSE name. At that same point in time, Moonchilde took the last
public release of that code and began a series of improvements and extensions.
 
     That code was released as PernMUSH, named for the MUSH that Moonchilde
was running. The last released version of that code was version 1.15, at
the end of November 1991. PernMUSH itself had switched over to TinyMUSH 2.0,
which Moonchilde had co-written with Glenn Crocker (Wizard of TinyCWRU);
there was no longer a reason for Moonchilde to maintain this code.
 
     In January of 1992, Amberyl began working on the PernMUSH 1.15 code
release, for TinyKrynn. She took over the code, which no one was supporting, 
and is continuing to work on extending this code, as well as improving its
compatibility with TinyMUSH 2.0.  She changed the name to PennMUSH
(named for her school, the University of Pennsylvania), to avoid the
confusion that resulted from PernMUSH actually running TinyMUSH 2.0.
 
      PennMUSH is memory-based; TinyMUSH is disk-based. PennMUSH can
run in very little disk space, but very large databases (25,000+
objects) can take up a prohibitive amount of memory. TinyMUSH has a
fairly large initial memory requirement, and uses a lot of disk space,
but has the advantage of being more efficient, as well as a vastly
slower rate of growth in memory usage, once the database gets to about
ten thousand or so objects.  It is possible to switch from PennMUSH to
TinyMUSH, as well as vice versa, so you are not "stuck" with any one
code.

      In January of 1995, Amberyl passed on her mantle to Javelin
(aka Paul@Dune, Alan Schwartz), who is now the maintainer of the
primary public distribution in development. He released two patchlevels
numbered "dune-1" and "dune-2" before releasing PennMUSH 1.50 pl11 and
later distributions. The numbering scheme changed again with PennMUSH
1.6.0 (see CHANGES-9).

      TinyMUSH 2.0 is capable of reading in databases from all PennMUSH
versions (though some optional features may have to be configured out of
the database before handing it off to Tiny). A program to convert
PennMUSH 1.50 format into TinyMUSH 2.0.6 format is available from
Amberyl via email; she hasn't gotten around to writing a converter for
later formats yet.

      A MUSH manual should be available at caisr2.caisr.cwru.edu,
ftp.math.okstate.edu, primerd.prime.com, or from wherever you got this
code from. The manual should be numbered version 2.007 or higher.

      If you are planning on modifying the source code to PennMUSH,
you'll probably want Javelin's Guide for PennMUSH Gods, which should
be available where you got this code, or, in hypertext, as
http://mellers1.psych.berkeley.edu/~alansz/guide.html

      Enjoy!

============================================================================

II.  Installation (new users)

     DISCLAIMER: Before attempting to run a MUD of any sort, you should
have some reasonable knowledge of UNIX and C.  If you do not, it is
_strongly_ suggested that you learn UNIX and C to some reasonable level
of competency before attempting to set up a MUSH.
 
     The MUSH directories are organized fairly simply: source code is in
the src subdirectory, with RWHO-related stuff in the RWHO directory
below it, and ident-related stuff in the IDENT directory below it;
header files are in the hdrs subdirectory; all things related to
running the game itself are in the "game" subdirectory. That directory
contains four subdirectories -- "data" (current databases), "save"
(backup databases), "txt" (text files), and "log" (log files).

     First, type 'sh Configure' in the top directory. This script
will ask you some questions and attempt to identify the proper Makefile
settings for your system. The default answers are very likely to be
correct, except that if you have gcc 2.0 or later, you should generally
prefer to compile with that than with your system's cc compiler.

    Configure will create a Makefile, a config.h file, and
a confmagic.h file. Probably you don't want to modify these, though
you could tweak the Makefile if you like. If that's necessary,
please report it to me so that it can be corrected in 
future versions.

EITHER:

     Then, copy options.h.dist to options.h and dune.h.dist to dune.h.
Note that these files stay in the top directory, as there is a symbolic
link to them from the hdrs directory.
     Then, edit options.h.  The file is fairly liberally commented.
You should definitely read the entire thing before figuring out what
you want to change.
     Do the same with dune.h
     Also, cp game/mushcnf.dst to game/mush.cnf.

OR:

     Type 'make update', and answer all the questions about
which MUSH options you want. 

     If you want the chat system, set CHAT_SYSTEM to 3 or 4. If you don't
want it, set CHAT_SYSTEM to 0. PennMUSH is now intelligent enough
to convert db's back and forth automatically.

     If you use CHAT_SYSTEM 3, the initial default chat channels are
listed in chat.c. You can change these defaults at runtime (read
the help for @channel, and put the relevant commands on the @startup of
an object). CHAT_SYSTEM 4 doesn't hardcode the chat channels, and
is recommended.

     You do not need to change any of the other header files.

     You next have to make sure you're set up for the IPC you need for
your machine. The only IPC package which is guaranteed to work is
bsd.c. Nick Gammon <nick@connexus.apana.org.au> is responsible for
the WIN32 port, and can answer questions about compiling for Windows 95/NT.

     Now, finally, edit src/Makefile.  Pick your compiler, memory
options, and other stuff.  For now, you will not want to run with any
RWHO or IDENT options, so just use the default there.

     Do a "make install". This will build all the necessary files, and
set up some symbolic links for the restart script.  You will need to
use "mkindx" to build the indexes for news and help (and events, if
you're using that). The format is 'mkindx <text file> <index file>'.
You must change the index file every time you change its associated
text file.  The restart script automatically builds the indexes for you
every time you start the game. You do not need to worry about the
"extract" and "dump" utilities.

     If you plan to run multiple MUSHes, you may want to do a 
"make customize" which will run a script to help set up a separate
customized game subdirectory for each MUSH (run it once per MUSH you
plan to run). Files in these subdirectories will already be
customized in many ways, so what follows may be slightly different. :)

     The next step is to create your configuration file. In the game
directory is a file called "mush.cnf". You may want to rename it
<your MUSH name>.cnf.  This is a list of all runtime configuration
options with their default settting. Change them as you see fit.
IMPORTANT: do not _delete_ any parameters. They all need to be there.
 
     Next, you must edit the restart script. You will probably want
to change the INDB to indb.Z, and you almost definitely will to change
GAMEDIR. That should be whatever directory the restart script is in.
You will also probably need to change the name of the configuration file,
as well as possibly some of the other file names, depending on what you
chose in the config file. The restart script is written for sh, and
assumes a fairly standard Berkeley UNIX setup. If you're on a HP-UX 
or SysV machine, for example, you may need to change the restart script 
a bit (the ps options, for example). 
 
     You should now be ready to start the game.  This distribution comes 
packaged with a basic database - a God character, starting room, and master 
room. This file is called game/data/minimal.db.Z.  You will probably want 
to rename this file  to indb.Z (it needs to be the same as INDB in the 
restart script).  The god character "One" has a default password of
"one", which you should change immediately (via @password).
options.h has the Master Room as #2 by default; in the provided database,
this room is created for you.
 
      Now you should be set -- all you have to do now is customize the
.txt files in the game directory.

      The logfiles in the "log" directory generally contain useful
information. You will probably want to read your main logfile (defined
in the restart script) every time, since errors and other important
messages get printed to that logfile.
 
      If you have any problems, feel free to contact Paul via email
at dunemush@mellers1.psych.berkeley.edu. PLEASE include the version
number you are attempting to compile, the type of machine and operating
system you are using, and, if possible, the address of the MUSH.

============================================================================

III.  Conversion Guide (previous users)

1. dune.h/options.h/mush.cnf

      The 'make update' command will run the update.pl program,
which examines the current dune.h and options.h files, compares
them with dune.h.dist and options.h.dist, and reports any new
or removed options which you can choose to define (or not)
interactively. It's designed to make upgrading your dune.h/options.h
from patchlevel to patchlevel a much easier process.

      Assuming you've unpacked the new patchlevel in a directory
called new/, and the old one in a directory called old/, you should
copy your old dune.h and options.h files into new/, and then
type 'make update'.

      Make update also updates your mush.cnf file. Again, copy
your old mush.cnf file to new/game/mush.cnf and run make update.

2. Database format

      This MUSH version will read databases along the main branch of
MUSH evolution -- TinyMUD, vanilla TinyMUSH, MicroMUSH, and all
Pern/PennMUSH versions. If you need to convert a TinyMUSH 2.0 database,
please contact Amberyl, and she'll mail you an extension to 2.0 that will 
dump a 1.50-readable flatfile.

      Starting from release "Dune-2", PennMUSH uses the version header
in the database to automatically read the db correctly, no matter what
options you have set, and to write a db which reflects those options.
If you plan to convert a PennMUSH db to TinyMUSH 2.0, you'll have to
unset all the options which add to the db (except the CHAT_SYSTEM),
start up like that, and then shutdown to dump a plain PennMUSH pl10 db.
You will lose all special info (warnings, etc.) in that db, so keep a 
copy of the original!
 
      It might be necessary to do some conversions, depending on
what version you are converting from. The "ADD_<whatever>" options
govern the conversions; to convert, compile with whatever
ADD options you need defined, start up the game, do a @shutdown,
recompile with those options turned off, and then start the game again.
 
      If you are upgrading from 1.50.p7 or 1.50.p8, you will not need to
do any conversions. From PennMUSH 1.50 versions before patchlevel 7, you will
need to define ADD_POWERS. If you have a 1.x MUSH database dating before
1.50, you should ftp PennMUSH 1.50 patchlevel 5, and convert your database
to 1.50 format, then follow the directions for ADD_POWERS above.

      If you do not do the conversion correctly, when you attempt
to start the game, you will get an error message like "bad attribute"
in the logfile, and the MUSH will refuse to start. You will definitely
want to back up your database before attempting to do any conversions.

      If you are upgrading from patchlevel 5 or earlier, please note
that  in patchlevel 6, compile-time configuration options were moved
into options.h, and the restart script was written in sh instead of csh.

      Please read the CHANGES files. They contain a large amount of
important information. A list of code changes that affect players is
given in news.txt. You may want to clip that section for your own news file.

3. Improved destroy code

NOTE: Past versions of PennMUSH were vulnerable to some types of
database corruption. In particular, a room could lose track of its
exits, which would then take up space in the database, but not be
accessible by any ordinary method.

PennMUSH 1.6.0 identifies these corruptions and fixes them. When the
MUSH first does an @dbck (about 10 minutes after startup) you may get
a bunch of messages like this in your netmush.log:

ERROR: Exit Out;o(#123E) leading from invalid room #456 destroyed.

and

Object Out;o(#456E) not pointed to by anything.
Orphaned exit destroyed.

and 

Object Out;o(#789E) not pointed to by anything.
Moved to Room(#1234R).

Do not be alarmed about a burst of these messages in the first ten
minutes after startup. Most databases will have some of these orphaned
exits.

Do, however, inspect each of the rooms to which exits are moved, to
decide whether you want to welcome back the prodigal exits. It is likely
that many of the exits that get relinked may have been duplicated by
later building. (One room on my test database ended up with three North;n
exits and three south;s exits.)

If errors like this happen after that initial burst, it then merits
some concern. The initial burst of messages, though, should be a cause
for attention, but not for alarm.

[This message by RLM]
 
============================================================================
 
IV.   Additional Options
 
    There are two additional major things which you can change: IDENT
and RWHO. IDENT allows your MUSH to report now only a player's site
of connection, but their account name, if they connect from a site
which runs an ident daemon (e.g. netcom.com, crl.com, and others).

        MUSH provides an interface for connecting to an RWHO server.
RWHO servers allow players to see who is connected to many MUDs via
telnet, or, if the administrator allows it, via a direct RWHO command
from the game.
 
    There are three possible options for RWHO. The first is not to
use it. This is the default, and you can feel free to just keep it
that way.
 
        The second option is to send login info to a remote RWHO server.
This option is highly recommended, since it is simple and painless. It 
uses UDP to send the info, so there will be no slowdown of the game by 
enabling this. There are several steps to getting this set up.
 
        1)  Contact the administrator of an RWHO server and ask if you can
            send login info to that server. The names of administrators
            are generally in the MUDlist posted to rec.games.mud.misc.
            One of the larger servers is run by Moira (Jennifer Smith,
            jds@moebius.math.okstate.edu).  Try sending her mail, with
            the name and address of your MUSH.
        2)  The administrator will probably send you mail back within a
            day or two, with additional info. You will get a password
            and an address for the RWHO server. Change the appropriate
            things in options.h and recompile. You should then be set.
 
        The third option is to send info to the RWHO server, AND enable
reading RWHO server info from within the MUSH (via the RWHO command).
This is a BAD idea unless the RWHO server and the MUSH are on the same
LOCAL network. The reason for this is that retrieving RWHO info uses
a stream port, and the MUSH could freeze if the net between it and the
RWHO server went down. If you MUST run this way, you might want to talk
to mjr@decuac.dec.com about how to set up your own RWHO server.

    MUSH also provides an interface to the identd daemon on remote
sites. Players who connect from these sites can be identified not only
by site, but by account name. Like RWHO, you can choose to use IDENT
or not. If you choose to use it, the ident_timeout configuration option
in mush.conf lets you set the maximum number of seconds the MUSH will
wait to get an identd response. 

    Another option you may want to consider is allowing your MUSH
to receive remote messages from other MUSHes via rpage. This uses UDP,
and does not slow down or otherwise endanger the MUSH.  If you wish to
do this, you should contact Amberyl to get the rpage code, and compile
with ALLOW_RPAGE defined.

        You should then contact the Gods of some other MUSHes. You will
need, for each MUSH, to agree on a password. You will need to do a:
rpage/add OtherMUSH password=address.of.other.mush
and the God of the other MUSH will need to do a:
rpage/add YourMUSH password=address.of.your.mush

        The name of the MUSH must be the same as that in "@version",
aliases are allowed for additional entries, but one entry MUST be the
name the MUSH uses in its conf file.
 
    The final thing you may want to think about is compiling
announce.c or portmsg.c. These are port announcers; if your
MUSH ever goes down, you can set one up, and a message will be given to
a person attempting to connect to that port.  Read that file for
details. It is not an official MUSH piece of code; rather, it is a
freely distributable program available via anonymous FTP that is
included in this code because it happens to be fairly useful.
Paul suggests using portmsg - it appears to be more stable.

============================================================================

V.      Trouble-shooting

    If you ever run into trouble, the your first reaction should
ALWAYS be to back up your database. indb.Z.old is the file that the
MUSH saves indb.Z to when the game, restarted, indb.Z is the file that
the MUSH loaded at startup, and outdb.Z is the file to which the MUSH
is currently dumping the database.

    You can tell if a dump is (theoretically) complete by doing a
"zcat <database file name> | tail -10".  The last line should read
"***END OF DUMP***". If it doesn't, your database has been truncated
for some reason. Check the logfile. Possible causes include a full
process table, a full disk partition, or running out of disk quota.

        Occasionally the dump process may dump core. This is caused
by some sort of corruption in an attribute, normally. You can tell
if the dump process has died by looking in your data directory; you
will see something like "outdb.Z.#5#". Wait a few moments and check
on the file again. If it has grown, then the game is in the process
of a normal dump. If it hasn't, and there's a core file, then something
has gone wrong. You should definitely shout a warning that building
is not being saved.

        To attempt to fix the problem, do a @dbck to take care of any 
possible minor weirdness in the database, then try doing a "@dump/paranoid", 
and reading the checkpoint logfile (default is log/checkpt.log). This is 
slow, but it will write out an uncorrupted database, and tell you what it 
fixed. Back up that database and indb.Z, then figure out what you're going 
to do next: you can take the game down with a kill -9, or attempt to 
manually fix the problem by either @destroying the offending object, or 
attempting to reset the attributes on the object that are causing a problem.
If "@dump/paranoid" dies, you are more or less out of luck.

        To fix weirdness in numerical fields, such as location or flags,
use the "examine/debug" and "@fixdb" commands.  Don't do this unless you
know precisely what you're trying to fix, since it's possible to produce
database inconsistencies which will panic, crash, or hang the server.
 
        The game may crash from time to time. It will generate a
core file, usually; if you don't limit the coredumpsize or strip the
executable, you should be able to get some useful information out of
it, using a debugger. Paul is interested in stack traces. You can
do a stack trace in the following manner: Go into the directory where
you keep your source code, and type
    <name of debugger> netmud game/core
If you don't call your executable "netmud", substitute in whatever
you do call it.
 
        You are looking for variables set to bizarre values - attempts
to access objects that aren't there, attempts to use pointers which
point to nothing, and the like.
 
        If you are using the "adb" debugger (don't do this unless
you really have absolutely nothing else available), you will see
nothing. It's loaded and ready, though. Type "$c". This will print
out a list of the functions it called. Type "$q" to quit. You can't
really get much more useful information out of adb.
 
        If you are using the "dbx" debugger, type "where" to see
the stack trace. You can move through it using "up" and "down",
and see exactly what the sequence of calls was. You can also use
"print <variable name>" to see the value of a variable at the
time the game crashed.  The "gdb" debugger is similar to "dbx"; with
that, you can abbreviate "print" as "p".
 
        Paul appreciates news of any bugs found, and any patches
that have been written to deal with them. He is also interested in
any extensions that people make to the code, and requests that ones
that are of more than just local interest be sent to her for inclusion
in the next release of this code.
 
        One important thing to remember is, if the MUSH refuses to
start, there is probably a good reason. Check the MUSH log, and the
core file, if there is one. Make sure to back up your database before
attempting to restart -- remember that every time it restarts, it
overwrites indb.Z.old. If you restart three times and somehow manage
to trash your database each time (for example, a full process table
zero'ing out your files), you won't have a backup to restart from,
unless you've backed up your database before trying!

    You can also find helpful tips in Paul's Guide for Gods,
which is available on the WWW as
    http://mellers1.psych.berkeley.edu/~alansz/guide.html
and by ftp from mellers1.psych.berkeley.edu as 
    /pub/DuneMUSH/Guide/guide-single.txt

        This code has been tested on a fairly wide variety of machines
and operating systems. JT Traub (otherwise known as Moonchilde) ran
it on a DECstation; Ambar later worked with JT on stabilizing the code
on a NeXT, where it eventually was rock-solid stable. Please do not
bother these people with requests for help; they no longer maintain this
code. Amberyl worked on a Sun SPARC-series workstation,
and did fairly extensive testing on an IBM RS/6000, a MicroVAX II, and
various SGI workstations. There's no real reason why PennMUSH shouldn't
compile on a machine with a BSD-derived operating system and an ANSI
compliant compiler (non-ANSI compilers should also work, but no guarantees
are given here). It should probably should run under anything System V-ish
with some juggling of #include files and other  modifications (tell Paul
if you needed to make major changes to get it working). 

    Paul does his development on a Sun SPARC-series workstation,
but has a variety of test platforms.

        This version of code was sucessfully compiled on a several different
Sun Sparc-series computers running SunOS 4.1.1, 4.1.2, and 4.1.3, a NeXT
running Mach 2.1, some DEC machines running various versions of Ultrix, an
IBM RS/6000 running AIX 3.2, and some SGI workstations running IRIX 4.0.5. 
Previous versions have worked on an HP 9000/720 running HP-UX 8.0 and
various 486 PCs running Linux; this version should, as well.
 
        If you have serious problems, contact Paul and he will
try to help you. Email is the best way to get a fast response;
in an emergency, you can bother him on a MUD, but for code problems,
email will probably get you a better response.
 
============================================================================
 
VI.     Amberyl's Comments

        These are in the first person.  :)
 
        I've been working with this code for a year and a quarter now.
I can't claim that it's particularly elegant or inspired; all I can say
is that it works (most of the time), and that I've had fun writing it.
I'm also hoping that it's quite readable; the sections I've added or
revised tend to be quite heavily commented.

        I'm willing to support this code and listen to whatever complaints,
suggestions, and screams for help you might have, with a great deal of 
patience (usually). I am interested in any changes that you might make to 
the code, as well as anything you might need to have done in order to get
PennMUSH to compile and run on "unusual" systems.

    If you mail me with bug reports or other problems, you MUST
tell me the following, or it's likely I won't be able to give you useful
information:

1. PennMUSH version number
2. The type of machine you are using (Sun SparcStation, IBM RS/6000, etc.)
3. The operating system and version (SunOS 4.1.2, AIX 3.2.4, etc.),
4. The compiler and compiler version (gcc 2.4.5, SGI cc 2.10, etc. -- the
   'file' command usually tells you the compiler version, if there's no
   built-in option like '-v' or '-V' to give it), 
5. Whether or not you have made any changes to the code.

PLEASE do not send full options.h or mush.conf files. Also, please don't
mail me asking me to help with debugging code you've added or asking for
details on how to code something. I've commented the code so anybody with
even a little bit of competence in C should be able to read and modify it;
I'm interested in _finished_ changes, not half-completed things I need to
debug myself.
 
        A number of people have been contributed a lot, directly and 
indirectly, to PennMUSH; many of them are credited in copyright.h.  
Read the file and embarrass them the next time you see them.  ;)
 
        PennMUSH 1.50 patchlevel 3 contains the promised parser rewrite.
A great deal of the code is derived or directly taken from the TinyMUSH 2.0
parser; credit goes to JT Traub (Moonchilde) and Glenn Crocker (Wizard)
for writing the thing in the first place. In most cases, the 1.50 parser
should now be functionally identical to the parser in TinyMUSH 2.0.9; 
see the news file for a brief summary of the changes. Major differences 
between the 1.50 and 2.0 parsers are almost certainly bugs, and should
be reported to me.

        I do have a life, though, and academics/job/social stuff
take priority. Thus, don't get too upset if it takes me a while to
add your pet hack.  :)  I'm generally happy to discuss code and
life in general, though, so if you see me on a MUSH, feel free to
say hi.
 
        Enjoy your MUSH, and feel free to email for help.
 
 
              --  Lydia Leong  (lwl@eniac.seas.upenn.edu)
                  "Amberyl" just about everywhere

============================================================================

VII. Paul/Javelin's Comments

    The stuff in Amberyl's comments still applies, just change
the name to "Paul" and the email address to mine. :)

        I am trying to keep extending the functionality of the server,
while optimizing and rewriting things wherever possible.  Ideas for
new features, and other discussion of this server should be sent to
the 1.50 mailing list:  pennmush@mellers1.psych.berkeley.edu
To subscribe, send mail to listproc@mellers1.psych.berkeley.edu,
and put 'subscribe pennmush YourNameHere' in the body of the message.
 

        -- Alan Schwartz (alansz@mellers1.psych.berkeley.edu)
           Paul@DuneMUSHes, Javelin just about everywhere else