Installing LPMOO
================

All required components of LPMOO have been included in this package:

  * Dworkin's Generic Driver (DGD 1.0.9.23)
  * DGD Networking Package (net-5)
  * Regular Expression Matching Package (rgx-0.3)
  * Patches for integrating the above with LPMOO
  * External DNS Resolver Daemon

Other things you will need that aren't included:

  - Larry Wall's `patch' utility program
  - a MOO database of your selection

If you don't already have a MOO database, you can use the LambdaCore database
or any other publicly available core. You can find LambdaCore at:

    ftp.parc.xerox.com:/pub/MOO/LambdaCore-*

Some people may prefer to bootstrap with a copy of LambdaCore that does not
contain $spell, an extraordinarily large object of questionable value. A copy
of such a database has been made available:

    ftp.ccs.neu.edu:/pub/mud/mudlibs/lpmoo/LambdaCore-*-sans-spell.db.gz

The so-called Minimal DB is also included with this distribution, in the event
you wish to write your own core from scratch. To use it, turn on the
`eval_backdoor' option in etc/moo.cf and bootstrap with the file
./Minimal.db. (You must turn on `eval_backdoor' in order to begin programming,
since the .program builtin verb is not functional in this release of
LPMOO. See the file doc/backdoor for more details.)

Installation Steps
==================

Please carefully follow these steps to install LPMOO, in sequential order:

 1. In the top-level directory of the distribution, type:

        make prepare

    This will apply all the necessary patches to the copy of DGD included
    in this distribution to use LPMOO.

 2. If you want to include networking support, type:

        make net

    This will install the dgd-net package, which is now supported in this
    release.

 3. If you're low on disk space, compress some files in the distribution:

        make space

    Don't worry if this doesn't work. You can just delete the files it
    tries to compress if you don't care about them. They are for your
    reference only from this point on.

 4. Edit the file `etc/dgd.cf':

      - Set `telnet_port' to be the port you want to accept user
        connections on. (If networking support is installed AND multiple-
        port listening is enabled, this option is ignored. See ./README.)

      - Set `binary_port' to be a secondary port to receive connections
        on. (See ./README for more details.)

      - IMPORTANT: Make sure `directory' is set to be the _absolute_
        pathname of the ./mudlib directory.

      - Set `users' to be a reasonable maximum number of on-line users
        (up to 255). This number can be adjusted later as needed.

      - If desired or needed, change `objects' to be a maximum value for
        the number of LPC objects to hold in the system. Note that MOO
        verbs as well as MOO objects count as LPC objects. This number
        can be adjusted later as needed. The current maximum for this
        number is 65535.

      - If desired or needed, change `call_outs' to be the maximum number
        of forked/suspended tasks to allow in the system. This number can
        be adjusted later as needed.

 5. Edit the file `etc/moo.cf':

      - Set `oob_prefix' to be your desired out-of-band data prefix. If
        you don't want to support out-of-band communication, set this
        to `NONE'. (See the LambdaMOO Programmer's Manual for more
        information about this option.)

      - If networking support is installed and you want to support outbound
        connections, set `outbound_net' to `YES'. Otherwise set it to `NO'.

      - If networking support is installed and you want to support multiple
        inbound connections through multi-port listening (see ./README),
        set `mport_listening' to `YES'. Otherwise set it to `NO'.

        NOTE: If you set this to YES, your db must be configured to open a
        network port from #0:server_started. Otherwise, you will be unable
        to connect. See doc/builtins/listen for an example. You may need to
        leave this disabled until you make the necessary modifications to
        your db.

      - If you want the server to display *** Connected *** messages and
        the like, set `server_msgs' to `YES'. To let your db be responsible
        for all such messages, set it to `NO'.

      - Make sure `timezone' is set to the abbreviation for your local
        timezone.

 6. Build DGD.

    The source for DGD lives in the dgd/src subdirectory. By default, DGD is
    ready to build under NetBSD with gcc.

    To compile for a different kind of host, you must:

      - Change the definition of HOST in dgd/src/Makefile.
      - Copy the correct file to dgd/src/host/Makefile.

    Consult the file dgd/doc/Platforms for details on what to do on your
    particular host.

    When ready, cd to dgd/src and type:

        make install

    You may see a few warnings that are safe to ignore:

      - conflicts: 1 shift/reduce
      - compiler.c: warning: decimal constant is so large that it is unsigned

    If the build completes successfully, free some disk space in dgd/src with:

        make clean

 7. Create a DGD state dump file. LPMOO can only be started from a state
    dump; it cannot be started without a database to work with, so you
    must have a LambdaMOO-format database available to bootstrap from.
    (See above for suggestions if you don't already have one.)

    Use the following command to create a state dump file from the
    top-level directory:

        make bootstrap db=PATH-TO-MOO-DB-FILE

    Note that `PATH-TO-MOO-DB-FILE' should be the path to your own MOO
    database file, which can be anywhere on your filesystem. Do NOT copy
    your database anywhere; just give the pathname. A symbolic link will
    be made from etc/moo.db to the path you give.

    Depending on the size of your db file, the bootstrap process may take
    some time. You may also run out of memory. If that happens, edit
    `etc/moo.cf' and reduce the `memory_thresh' option by 1 or 2, then
    try again.

    This process writes a binary file, linked from `etc/dgd.db', that is
    used to restart LPMOO. This is also where regular checkpoints are
    written, so future restarts will always use the most recent version.

 8. Start LPMOO. This can be done with the following command from the
    top-level directory:

        make run

    This starts LPMOO with the most recent state dump. A LambdaMOO-style
    server log will be written to `etc/moo.log'. In addition, a DGD log
    will be kept in `etc/dgd.log'. (These are symlinks to the real files,
    actually kept elsewhere.)

    The process ID of DGD is saved in the file `etc/dgd.pid'. You can
    later kill the process with:

        make kill

    However, the recommended way to shutdown the server is to use the
    shutdown() builtin function, so that the state of the system can be
    properly saved. In either case, you may then need to do:

        make clean

    before starting the server again.

 9. (Optional) Install support for hostname <-> IP address translations.
    Please read doc/dns-resolver for complete details.

    Without this support, connection_name() will always return IP addresses
    rather than hostnames (so domain-based site locking may fail), and
    the host argument to open_network_connection() must always be an IP
    address.

10. Connect to your MOO!

    NOTE: If you enabled mport_listening but don't have your database
    configured to open network ports, you won't be able to connect. Reread
    step 4 above carefully.

What Next
=========

If you didn't finish reading the ./README file, please finish that now.