Getting Started
===============

If you...					Do this...

* want a general description of LPMOO		* read ./BLURB
* are setting up LPMOO for the first time	* carefully read ./INSTALL
* are upgrading from a previous version		* read the next section
* have any problems				* read doc/troubleshooting

Upgrading
=========

You should keep this LPMOO distribution separate from your current LPMOO tree
but copy files as needed while upgrading:

1. Upgrade the dbsaver in your current LPMOO.

   - If you were previously using LPMOO version 1.1.6 (only), copy the file
     src/dbsaver-1.1.6.cdiff from this distribution to the top of your 1.1.6
     LPMOO tree, and then do:

         patch -p0 < dbsaver-1.1.6.cdiff

   - If you were previously using LPMOO version 1.1.8 or later, copy the
     file mudlib/obj/dbsaver.c from this distribution to the same place in
     your current LPMOO tree.

   - With a wizard character on your MOO, do this:

         ;"/lpc/utils":update("/obj/dbsaver")

2. Make a text dump of your current LPMOO.

   - From within your MOO, call dgd_checkpoint_db(). Note that beginning
     with version 1.2, use of this function has been deprecated; in the
     future you will want to call dump_database() with a non-zero argument.

     The text dump will take some time to complete. Be patient! You may
     get a "Task ran out of ticks" traceback when it finishes; this is
     okay. Beginning with 1.2 you will not get this error any more.

   - Shutdown your current MOO.

3. Proceed carefully with the instructions in the ./INSTALL file.

   - Where it says you need a database to bootstrap from, specify the file
     created in the previous step; it is usually etc/checkpoint.db (under
     your old tree), although beginning with 1.2 the file is named
     etc/text.db instead.

What's New
==========

For a detailed list of changes between this version and previous versions,
please consult the file doc/Changelog.

Since version 1.1.8, the following significant changes have been implemented:

  - DGD has been upgraded to take advantage of new efficiency improvements.
    LPMOO should now run slightly faster and with less memory than before.
  - Several optimizations have been made to LPMOO's internal code.
  - An optional argument has been added to the callers() builtin to return
    the call stack for the specified task (see doc/builtins/callers).
  - A new datatype, a buffer, has been added for manipulation of binary
    data (see doc/binary-data). Note that custom LPC functions you write
    which return strings containing binary data will return buffers.
  - The renumber() builtin has been optimized to avoid scanning the entire
    db (consuming time and memory) whenever possible.
  - ticks_left() and seconds_left() are now more accurate, and the previous
    continuous-suspend problems have been fixed.
  - The dbsaver has been improved, and should not have problems with large
    strings.
  - dgd_checkpoint_db() is obsolete, in favor of dump_database(1).
  - #0:checkpoint_started is called with an integer argument, specifying
    whether the dump being made is (0) binary or (1) text.

Networking Support
==================

This version of LPMOO supports both outbound and inbound networking, if the
dgd-net package is installed (via step 2 in ./INSTALL).

Outbound networking is accomplished through the same open_network_connection()
interface as is provided in the LambdaMOO server. However, an optional third
argument has been added; see doc/builtins/open_network_connection for details.

Inbound networking, also known as multiple-port listening (or MPL) is
supported through two additional builtin functions, listen() and
unlisten(). See doc/builtins/listen and doc/builtins/unlisten for complete
details.

NOTE that as of version 1.1.8 of LPMOO, the order of arguments to listen()
has changed for consistency. In this release, backwards compatibility has been
maintained, but please see doc/builtins/listen for the correct usage.

If the `mport_listening' option is enabled, LPMOO will not automatically
listen for connections on any port; you must do this yourself from the
#0:server_started verb. See doc/builtins/listen for an example.

Binary Ports
============

DGD (and therefore also LPMOO) supports two forms of inbound connections:
telnet and binary. Telnet connections are preprocessed into lines of input
according to the telnet protocol before being processed by LPMOO. It is also
possible to toggle the ECHO telnet option on telnet connections (see
doc/builtins/dgd_set_noecho).

Binary connections support complete binary transfer of data between remote
clients and DGD. By default, DGD opens a binary port and listens for
connections on the port listed in the etc/dgd.cf configuration file under
`binary_port'. Binary connections can also be received on any port opened by
the listen() builtin function, if multiple-port listening is enabled.

LPMOO attempts to handle binary connections in the same manner as telnet
connections; that is, it preprocesses input into lines terminated by newline
characters before sending them to the command parser. Telnet options are not
recognized in binary connections. Also, the input buffer for a single line
received on a binary connection can grow to as much as 64K, compared to the 2K
line limit buffer for telnet connections. This can be useful for connections
made by non-humans in which input lines may be extraordinarily long.

Certain characters are also filtered from transmission in telnet connections,
most notably the escape (ESC, ASCII 27) character. If you plan on sending
binary characters to clients, you would be best off using the binary port.

Disk-Based Operation
====================

LPMOO is built on DGD, a disk-based server. This means that during normal
operation, unused objects are transparently swapped out to disk so that the
overall process size is kept manageable. In this context, MOO verbs as well as
MOO objects count as independent "objects" in DGD.

You can tweak the effectiveness of the swapping algorithm by modifying certain
parameters in the etc/dgd.cf configuration file. See the file
doc/troubleshooting under the headers "system response time is slow" and
"LPMOO uses too much memory" for details.

Documentation
=============

You will find documentation for various aspects of LPMOO in the ./doc
directory. The doc/builtins directory contains files which describe each of
LPMOO's proprietary builtin functions.

A list of differences between LPMOO and LambdaMOO can be found in the file
doc/differences.

Documentation for MOO itself should be obtained from:

    ftp.parc.xerox.com:/pub/MOO/ProgrammersManual.*

More documentation for LPMOO is also available on the Web:

    http://www.ccs.neu.edu/home/rob/lpmoo.html

-- 
Robert Leslie
rob@ccs.neu.edu