============================================================================ Installation Guide to PennMUSH 1.8.x ============================================================================ This file explains how to install PennMUSH. It comes in three parts: A. Important background B. Installation from source (recommended) C. Installation of precompiled binaries (only for Windows platforms) If you are upgrading from a previous PennMUSH release, this is probably not the file you want to start with. Read the UPGRADING file first. 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. (Note that even people using the Windows ports are encouraged to know UNIX, because that's the paradigm that PennMUSH was built with, and most resources will be written with UNIX is mind.) You may also want to take a look at Javelin's Guide for PennMUSH Gods, at http://pennmush.org/~alansz/guide.html or by ftp from pennmush.org, /pub/PennMUSH/Guide ============================================================================ A. Important background Here's a quick picture of the organization of the MUSH directory tree. The "src" directory contains C source code. The "hdrs" directory contains header files for the source code. The files used by a running MUSH are in the "game" directory, which includes subdirectories "data" (current databases), "txt" (text files and directories for building them), "log" (log files), and "save" (backup databases). Finally, the "hints" directory is used during the installation process, the "po" directory holds translation message files, and the "os2" directory contains files of using in building for OS/2. pennmush--+-> src +-> hdrs +-> game ------+-> data | | | +-> txt -------+-> nws | | +-> evt | | \-> hlp | | | +-> log | \-> save +-> hints +-> os2 +-> po +-> utils \-> win32 PennMUSH has been tested on a fairly wide variety of machines and operating systems including at least: NeXT Mach 2.1 Sun Sparc SunOS 4.1.x Sun Sparc and i386 Solaris 2.x DEC Decstation Ultrix 4.x and OSF/1 DEC Alpha OSF/1 and Linux SGI Indy Irix 5.x and 6.x HP 9000 series HP-UX 8.x IBM RS/6000 AIX 3.2 IBM S/390 Linux Novell Unixware SVR4 Linux FreeBSD AT&T SVR4 Windows 95/NT cygwin and MSVC++ OS/2 There's no real reason why PennMUSH shouldn't compile on any 32-bit or better BSD, System V, or POSIX operating system. Javelin does his development on a Linux PC these days. If you have serious problems, contact Javelin 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. ============================================================================ B. Installation from source The quickstart version of the installation is: 1. On win32 only, install proper tools or read win32/README.txt. 2. sh Configure -d or some variant 3. create options.h, or make update 4. make install 5. possibly make customize 6. Read game/README and follow those instructions Here's the process in detail: 1. If you're running on win32, there are two options known to work: a. Compile with MS VC++ or VS.NET. If you want to do this, read win32/README.txt and then skip down to step #6 below b. Compile with the Cygwin unix emulation tools (http://www.cygwin.com) In addition to the base cygwin stuff, you'll want the following packages: binutils, gcc, make, patch, perl, exim (the latest *source* code package, not the binary) (gcc 3.2 is recommended.) These are also recommended: gettext, gettext-devel, indent, vim or emacs It is recommended that you install the tools under C:\CYGWIN and that you read the Cygwin FAQ if you get messages about HOME not set. Put the pennmush .tar.gz file in C:\CYGWIN\USR\SRC. Don't uncompress it with Winzip or other windows tools! VERY IMPORTANT: The rest of the instructions assume that you have started up a bash shell and are running commands under that shell -- they won't work right if run directly from a DOS shell. cd /usr/src, and unpack the .tar.gz file with: tar xfz pennmush-whatever.tar.gz 2. cd pennmush. On Unix systems: ./Configure -d On cygwin systems, try ./Configure -d, but if it fails, try: . Configure (That's a single period, a space, and Configure) When you get to the question about hints files, choose 'cygwin'. For all other questions, the defaults should work. 3. EITHER: Copy options.h.dist to options.h. Note that these files stay in the pennmush directory. Edit the file. It's liberally commented. On Cygwin systems, you should *not* define NT_TCP with cygwin, and you should use MALLOC_PACKAGE 0. You may use an COMPRESSION_TYPE you prefer. Also, cp game/mushcnf.dst to game/mush.cnf and edit. On cygwin systems, you probably should not use compressed database, so modify that bit. OR: Type 'make update', and answer all the questions about which MUSH options you want. You should not need to change any of the other header files. 4. On cygwin systems, add to the CCFLAGS in the Makefile: -I/usr/src/exim-4.20-1/minires (or whatever the latest exim source directory is) 5. Do a "make install". This will build all the necessary files, and set up some symbolic links for the restart script. You will probably receive a few compilation warnings, which can generally be ignored. 6. 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. :) This is probably broken. 7. Read game/README and follow those instructions. A 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. Javelin suggests using portmsg - it appears to be more stable. ============================================================================ C. Installation of precompiled binaries (only for Windows platforms) A pre-built binary is frequently available for win32 users who don't want to customize their MUSH server, and don't feel like compiling it themselves. This binary distribution may not contain the src, hdrs, hints, or os2 directories and may be missing several key files (like Configure) from the pennmush directory. It does include the options.h that it was built with, as an aid to those who decide later that they want to customize the server; they are useful as a baseline to work from. Using the pre-built binary is fairly simple; adjust your configuration file as in game/README, then go to the game directory and run PennMUSH.exe (you may need to use PennMUSH /run or PennMUSH /start). Alternately, if you want the MUSH to automatically start each time you turn on your machine, you can install it as a system service by running 'PennMUSH /install'. PennMUSH can be removed from service status via 'PennMUSH /remove'.