5.1.2 Compiling a MUCK

UNIX gurus and C buffs should have little difficulty compiling a MUCK. For the rest of us, it is a potentially frustrating experience. This section of the manual is addressed to the rest of us: sysadmins and C developers, you can use this time to go toggle in a new kernal from the front panel of a PDP-11, just to keep your hand in.

MUCK is not a shrink-wrapped, plug-and-play product. It is, rather, a large freeware application developed over a number of years by skilled coders who are willing to devote innumerable hours to making something for other people to use and enjoy. It is assumed that you — the site administrator — have reasonable facility with the UNIX operating system and a basic understanding of how to configure the program by editing C source code configuration and header files. In other words, like UNIX itself, MUCK is quite user-friendly, but rather choosy about who its friends are. The following overview may help you get on speaking terms with your new server.

It is of course madness to try to set up a MUCK without knowing UNIX. Nonetheless, people often try, and often succeed. A good book on UNIX will be a worthwhile investment if you are going to be the MUCK's site administrator.

If the set up goes smoothly — that is, if your system has everything where MUCK expects it to be — this information should be all you need. If you encounter compilation errors, you'll need to enlist help. Those sysadmins and C developers will be through toggling in their microkernals by the time you've gotten that far, and will no doubt be MUCK'ing somewhere. Go to a large MUCK, and try a public shout, or paging helpstaffers and wizards, asking if someone can lend a hand compiling a MUCK.

Getting your server up and running involves the following steps:

1. Getting a compressed, archived file containing the source code.
2. Uncompressing the files.
3. Editing configuration files
4. Compiling the source code
5. Specifying database files
6. Starting and logging onto the server

Getting the Server:

The MUCK platform has evolved over a number of years, from TinyMUD, written by James Aspnes, to its current incarnation: TinyMUCK, FuzzBall version 6.0, developed primarily by Garth Minette. The most current and authoritative version should be available at ftp.belfry.com/pub. You may want to get the archive of standard MUF programs and a start-up database as well.

1. pub/fuzzball/fb6.0.tar.gz
2. pub/fuzzball/fbmuf.tar.gz
3. pub/fuzzball/basedb.tar.gz

Put the fb6.0 file where you want the top level of your MUCK directory to go, perhaps in your home directory.

Uncompressing the Files:

The files you just got are compressed archives of a great many files and directories.

To uncompress them, type gunzip <filename>. For example

====================================
  gunzip fb6.0.tar.gz
====================================

If you get something like gunzip: command not found, try unzip:

====================================
  unzip fb6.0.tar.gz
====================================

This uncompresses the archive. You now need to extract individual files from the archive with the tar command (`tar' for `tape archive').

====================================
  tar -xvf fb6.0.tar
====================================

The switches -xvf tell the system that you want to eXtract files from an existing archive File, and that you'd like it to do so Verbosely, so you can see what it's doing.

Type ls to `list files' in your current directory. You should see, among other things, an entry for fb6.0/ (the / slash may or may not appear). This is the directory holding the server.

If you got the dbase and MUF files, move them to the correct spots in the server directories...

====================================
  mv fbmuf.tar.gz fb6.0/game/muf
  mv basedb.tar.gz fb6.0/game/data
====================================

... and change directories (cd) down to the directories holding the files and unpack them in the same fashion.

Editing the Configuration Files

In directory fb6.0, you should see a file called INSTALLATION. It gives succinct instructions for setting up the MUCK. Type cat INST* to list it on your screen.

You will be editing a few files (include/config.h, game/restart, and possibly include/params.h or include/autoconf.h). It is strongly recommended that you make a copy of these files before you start modifying them, so you can start over if something obscure goes wrong. In the appropriate directories...

====================================
  cp config.h config.bak
  cp params.h params.bak
  cp autoconf.h autoconf.bak
  cp restart restart.bak
====================================

You can either edit the files directly on the server, with text editors such as vi or pico, or you can download the files to your computer, make changes, and then upload them. Hereafter, the Manaul will simply instruct you to `edit' the files; do so in whatever way works best for you.

Much of what you'll be doing when editing these files consists of `defining' or `undefining' terms. A term is defined by beginning a line with the #define preprocessor directive, followed by the term and (optionally) its definition.

If a term is defined without a definition, such as...

====================================
  #define GOD_PRIV
====================================

... this simply means that the term is `true': the compiler can in effect check `Are we using God privileges?', and get a yes/no answer. In this case, the term is defined; it has a true value: so, yes, we're using God privileges.

If a definition is supplied, then the term is true, and has a specific value. For example,

====================================
  #define TINYPORT 8000
====================================

This means that, yes, we do have a specified default port to connect to: port 8000.

You can `undefine' a term in either of two ways: you can comment it out, or you can explicitly undefine it. To undefine a term, use the #undef preprocessor directive:

====================================
#undef ANONYMITY
====================================

To comment out a term (that is, to change it into a comment that people can read, but to be ignored by the compiler), enclose it in the strings `/*' and `*/'

====================================
/* #define DISKBASE */
====================================

In general, you should #undefine terms rather than commenting them out: doing so will undefine the term, even if it was defined somewhere else.

You won't need to change a very much.

In include/config.h:

Edit the file to the port you want to use.

====================================
  #define TINYPORT 8000
====================================

Port numbers below 1024 are reserved for system processes; use something higher than 1024, and lower than 65,534.

It's recommended that you leave all other settings the same, until you're familiar with each of them and have a specific reason for changing them.

You shouldn't need to change anything in include/params.h.

In game/restart:

This file is a shell script, a set of commands that execute conditionally, rather like a DOS batch file. In addition to starting and restarting the MUCK, it does some logging and error checking: it bails out if the MUCK is already running, so you won't have duplicate processes running, keeps a log of when the MUCK was restarted, and warns of conditions such as missing or damaged database files, or insufficient memory. You will need to make a couple changes to this file.

Near the top of the file, change the line which sets the variable holding the path name for the MUCK. If you left the name of the directory created when you un-tar'd the server as fb6.0, and didn't rename any sub-directories in the server directory, you would set the path variable as follows:

====================================
  set GAMEDIR = $HOME/fb6.0/game
====================================

The port number needs to be specified in restart as well:

====================================
  set PORT = 8000
====================================

The server process is called `netmuck' (the executable file that actually runs the server is `netmuck'). `Restart' includes necessary references to `netmuck'. On sites that have several M*'s running, it's a very good idea to rename `netmuck' to something else, or to call it by an alias, so that the sysadmin can tell at a glance what's what, and — more importantly — so that the restart script won't get confused by seeing two running processes called 'netmuck' and therefore refuse to start your server. If you're running the MUCK on your own machine, and know you'll only have one MUCK, the following step can be omitted.

Find the line that says...

====================================
  You probably won't need to edit anything after this line.
====================================

... so you'll know where to start making changes. A few lines into forbidden territory, you'll see the following line:

====================================
  set muck = `ps -aux | grep netmuck | wc -l`
====================================

Replace the word `netmuck' with something indentifiable as your MUCK. If your MUCK is called `Vanity Fair', you might change it to:

====================================
  set muck = `ps -aux | grep VanFair | wc -l`
====================================

And, the second to last line of the file:

====================================
  ./netmuck $DBIN $DBOUT $PORT >& logs/stdouterr.log &
====================================

Change `netmuck' here too.

====================================
  ./VanFair $DBIN $DBOUT $PORT >& logs/stdouterr.log &
====================================

Compiling the Source Code:

Now it's time to compile the server.

A very brief rundown on what's happening here: In addition to information files like README and INSTALLATION, and the server you just downloaded consists of quite a few files of `source code'... human-readable text files written in the C programming language. You'll use the `make' and `configure' utilities to create machine-executable code from the source files.

Change directories to game/src, the directory holding the source code. Type `configure'. This determines what flavor of UNIX you're running under, the location of certain files and executables, and so forth. This part should be quite straightforward. If it's not — if you get messages such as `No processor installed' or `Welcome to Macintosh' — log onto a large MUCK and find someone who can help.

Now, the (first) moment of truth: while still in game/src, type `make'. Watch arcane messages scroll by. Then, when they seem to have all done so, type `make install'. Watch more arcane messages. You may see some labled `Warning'. As long as the warning isn't followed by a `Fatal error', you should be OK. (Fatal errors are bad.)

If you get other compilation errors at this point, you'll need to track down a guru to help you out. Again, wizzes, helpstaff, and @shouts on large MUCK's are a good place to start looking for one.

Once you have the server compiled, you should tidy up a bit. In the compilation process, a number of `object files' were created... Object files are intermediate files created as the compiler generates the executables. After compiliation, you don't need them any more; they just take up disk space. In the game/src directory, type `make clean' to get rid of them.

Specifying Database Files:

You need to provide the server with a database to use at start up. You can use either the minimal database included with the server, or the standard start-up database included in basedb.tar.gz. The minimal database includes only two objects: Room #0, and God, player #1. The start-up database includes about 70 objects, including important programs and a couple rooms.

The start-up database is of course more convenient, but you may wish to use your own versions of the programs or to set aside some low dbrefs for players and other important objects. If you use the start-up database, the first objects you create will have dbrefs in the high 60's.

The minimal database is, well, minimal. You'll need to do a bit more work to get the place going, but you'll have greater control.

The files to be used for the database are defined in the `restart' script. We didn't change those: the server will expect to find files `std-db.db', `std-db.old', and `std-db.new'. The default file names are fine, but we need to create the files themselves.

In directory game/data... If you're using the start-up database

====================================
  gunzip basedb.gz
====================================

This should create a file named `basedb.db'. Type ls to make sure. If it created something else, use that file name below:

====================================
cp basedb.db std-db.db
cp basedb.db std-db.old
cp basedb.db std-db.new
====================================

====================================
cp minimal.db std-db.db
cp minimal.db std-db.old
cp minimal.db std-db.new
====================================

Starting and Logging onto the Server:

You're now almost ready to start the MUCK. One last thing... If you're on a public site, and edited the restart script changing `netmuck' to something like `VanFair', you need to either rename `netmuck', or create an alias for it.

In the `game' direcectory, type ls. You should see file `netmuck'. Rename that file with the following command:

====================================
  mv netmuck VanFair
====================================

If you made a copy of the restart file, you may need to make it executable at this point:

====================================
  chmod +x netmuck
====================================

...in the final column.

Type `ps -aux'. This will list all the processes running on the machine. If all is right with your world, you should see a process for it, a line with something like...

====================================
  ./VanFair data/std-d
====================================

...in the final column.

If you see too much stuff, and can't tell if the server process is in the list, filter it with the grep:

====================================
  ps -aux | grep VanFair
====================================

Quick and Dirty Trouble-Shooting:

If the MUCK compiled correctly (you didn't get errors when compiling, and you have a file named `netmuck' in your game directory), but you don't have a process running, then something went awry in the restart script. You should confer with your sysadmin or some other knowledgable UNIX-type about it. Meanwhile, though, you can use a simplified restart script. If the problem truly is in the restart script, and not in the server, this should get you up and running while you enlist outside help.

Move your current restart script to another file for safe keeping:

====================================
  mv restart restart.cp2
====================================

====================================
  mv data/std-db.db data/std-db.old
  mv data/std-db.new data/std-db.db
  ./VanFair data/std-db.db data/std-db.new 8000 >& logs/stdouterr.log &
====================================

(`VanFair' and `8000' are specific to our example: use the MUCK name and port number for your MUCK.)

Make the new script executable:

====================================
  chmod +x restart
====================================

This script won't provide all the error checking and logging that the full-blown one will, but there's also less to go wrong in it. With the new script in place, type `./restart' again.

(A common reason for the restart script to fail: You are running your MUCK on a server that is also hosting other MUCKs, and neither you nor the other MUCK admins renamed `netmuck'. Because the restart script uses this file name to see if the server is already running when you try to restart, and bails out if so, your restart script fails because it sees someone else's MUCK running as a netmuck process. The fix: rename netmuck and edit the restart script appropriately.)

We'll assume that you now have a MUCK process running. Congratulations.

Now you need to log on. There is only one character on the MUCK... #1, who is probably named `One'. #1's initial password is `potrzebie'. Connect to the MUCK with your normal client, and log in:

====================================
  connect #1 potrzebie
====================================

If you're running the minimal database, type @stats: savor this pristine and perfect universe.

It is imperative to change God's password from the default.

====================================
  @password potrzebie = <whatever>
====================================

You're done!