Setting up KQML
Ian Soboroff, Fall 1997
ian@cs.umbc.edu

You will need the following tools to build CARROT:
    - GNU gcc/g++ (preferably 2.7.2 or later)
    - GNU make (at least 3.71, preferably 3.75)
    - Tcl 7.5/Tk 4.1.  Most of the tools here are not known to work
      with later versions of Tcl, but they might!

KQML is known to build and run under
    - Solaris
    - IRIX 5.x, 6.2
    - Linux 2.0.x

If you get KQML running under another OS, let us know, so we can add
it to the list!  If this involves any patches, please send those along
so we can incorporate them into the distribution.  

You can find the GNU programs at ftp://prep.ai.mit.edu/pub/gnu or
ftp://wuarchive.wustl.edu/pub/systems/gnu.  Tcl can be found at
ftp://ftp.sunlabs.com/.

Building KQML
-------------

(1) You will need to edit several scripts in kqml/bin:

kqmlenv*
	Edit KQML_HOME to point to the kqml/ directory, and KQML_ANS
	to refer to the host on which you will run the Agent Name
	Server.  The ANS always runs on port 5500.
startans, stopans, viewlog 
	These should source the kqmlenv script in this directory.

(2) Source an appropriate kqmlenv script into your environment.

For example, in csh/tcsh, type "source kqmlenv.csh".  In sh/bash, type
". kqmlenv.sh".  This will add to your search path and also set
several environment variables needed by KQML.  After running the
kqmlenv script, "echo $KQML_HOME" should print out the kqml/
directory.

Several components KQML need these variables (at least KQML_HOME and
KQML_ARCH) to build properly, so it might be a good idea to source the
kqmlenv script from your .login file.

(3) cd $KQML_ARCH/build

The KQML area is set up to support several OS builds simultaneously.
$KQML_ARCH points to the OS-specific area for your current
environment.  You should think about building KQML for each
OS/environment that you will want to run CARROT agents in.  KQML
builds "out of the box" for IRIX 5/6 and Solaris 2.5.  It is known to
build with minor Makefile changes under Linux and pre-Solaris SunOS.

(4) make

Make sure that the 'make' you use is GNU make!

If the build fails for some reason, you can manually step through the
process as outlined in the build/Makefile.  Usually, the problem is an
unfound library.

(5) start an ANS

Start the agent name server by typing
      $KQML_HOME/bin/startans <name-for-ans-agent>

The ANS needs to run at port 5500 (or, more particularly,
IPPORT_USERRESERVED+500... IPPORT_USERRESERVED is 5000, and is
specified in the <netinet/in.h> include file).  You can change this by
modifying KQMLPORT_OFFSET in include/kqml/kqmllib.h, and optionally,
the use of IPPORT_USERRESERVED in src/router/router.c.

(6) If all has gone well, you should be able to type 'agentls' and see
something like:

my-ans (tcp-ip rags.cs.umbc.edu:5500:) 
admin-agent-ls (tcp-ip rags.cs.umbc.edu:39179:) 

agentls shows all agents registered with the ANS... in this case, the
ANS itself ("my-ans"), running on rags; and the agentls program, which
is an agent named "admin-agent-ls".

You should now be able to build and run the agents in the examples/
directory.

(7) Build TKQML

TKQML is not currently in the automatic build for KQML, so cd to
$KQML_ARCH/build/tkqml, and type 'make all install'