
	       Tileworld (The X Window System Version!)
				Copyright 1990, Martha E. Pollack

			     INSTALLATION GUIDE

The Tileworld system was designed and developed at SRI International,
Menlo Park, CA, by Martha E. Pollack, Michael P. Frank, and Marc
Ringuette.  This Installation Guide was written by Michael P. Frank and 
Martha E. Pollack.


CONTENTS (Search for these strings)
-----------------------------------
Introduction
Hardware and Software Requirements
Porting Tileworld to your System
Resolving Directory Dependencies
Setting Directory Permissions
Compiling the C Files
Invoking Lisp
Compiling the System


Introduction
------------

This guide will tell you how to install the Tileworld system.  Details of 
running experiments using Tileworld can be found in the accompanying User's
Guide; information about modifying or investigating the "guts" of 
Tileworld can be found in the Programmer's Guide.  Both of these other
documents are included in the collection of files you receive when
you port Tileworld to your own system.

Hardware and Software Requirements
----------------------------------

The Tileworld system is designed to run on a Unix machine with at
least 8 M of main memory. (Of course, experiments will run much more
quickly if you have additional memory.)  You'll need to be running
X-windows, and also have Lucid Common Lisp and CLX (the Common Lisp X
Interface).  We have developed and tested the system with Version 4.0
of Lucid Lisp.  We believe that it is likely also to work with older
versions but we haven't tested this.


Porting Tileworld to your System
--------------------------------

You can receive a complete Tileworld system by using the ftp facility.
Use ftp to connect to "ai.sri.com", login as "anonymous", and use your
last name as the password.  (By using your last name, we will be able
to identify you via ftp's logging facilities.  That way we can keep
track of who has copies of Tileworld and can then contact you if we
have new versions of the system, etc.)

After logging in, connect to the directory pub/tile (i.e., "cd
pub/tile").  Then use ftp to get the file "tileworld.tar.Z".  Make
sure you've turned on binary mode, because the file is compressed
(i.e., it uses 8-bit data).  The file is also tarred so you'll need to
uncompress it and then untar it.


Resolving Directory Dependencies
--------------------------------

Once you've gotten a copy of the Tileworld system, the first thing
you'll need to do is resolve the references among various Tileworld
files that point to one another.  Throughout the documentation and the
code you've just received, we call the directory that contains the
Tileworld system "~tile".  There are 8 occurrences of the string
"~tile" in the code; you need to replace each of these with the name
of the directory in which you've stored your version of Tileworld.
IT'S ALSO IMPORTANT THAT YOU REPLACE THEM WITH ABSOLUTE PATH NAMES
(I.E., NAMES THAT START WITH A SLASH /), RATHER THAN RELATIVE PATH
NAMES.

(Note: Although we use the symbol "~tile", you do NOT need to create a
"tile" user.  In the near future, we will use a shell variable to
facilitate this instantiation process.)

Here's a list of of all occurrences of the string "~tile":

Filename:		Occurrence:

tw.lisp:		(load "~tile/cl-util/defsystem")
			(setq defsystem::*central-registry*
				 "~tile/reg/")
reg/xtile.system: 	source-pathname "~tile/xtile/"
xtile/agent/foreigndefs.lisp:
			(load-foreign-files '("~tile/xtile/agent/twmove.o" 
			      	              "~tile/xtile/agent/twpush.o" 
			                      "~tile/xtile/agent/bfs.o" 
                			      "~tile/xtile/agent/heap.o"
		                    	      )
                        			    '("-lc")
                                    			    )
xtile/exper/exper.lisp:
			(setf *experiment-dir-name* "~tile/xtile/experiments")

The Programmers_Guide also refer to the directory containing the system
as ~tile.  


Setting Directory Permissions
-----------------------------

In general it's up to you to decide what kinds of permissions you want
to set (using chmod) for your ~tile directory and its subdirectories.
Please note, however, that the default is for Tileworld to save
its data into files in the directory ~tile/xtile/experiments, so
you'll probably want to give generous write permissions to that
directory, at least at first, so that you can run the demonstration
experiments as described below and in the Users' Guide.


Compiling the C Files
----------------------

The Tileworld planner makes use of a few files of C code, which you
need to compile.  From within your ~tile directory:

(1) Type cd xtile/agent
(2) Type cc -c bfs.c
(3) Type cc -c heap.c
(4) Type cc -c twmove.c
(5) Type cc -c twpush.c
(6) Type cd ../.. 
	to return to your ~tile directory.

Note that C code that is compiled on a Sun-3 can only be run on a
Sun-3; C code that is compiled on a Sun-4 can only be run on a Sun-4
or Sparc station.  So be sure to do these compilations on the same
kind of machine as you'll use for running Tileworld.


Invoking Lisp
-----------

Now invoke Lisp from within your ~tile directory.  You need a Lisp
Image that includes CLX.  Consult your local administrator to find out
the right Lisp to invoke on your system.


Compiling the System
--------------------

Within Lisp and in your ~tile directory:
1.  Type (load "tw")
     to define and load the system.  Because you haven't yet compiled the 
     system, Lisp may ask you whether it's alright to use source files.
     Say yes.
2.  Type (c)
     to compile the system.

You are now ready to run Tileworld experiments.  You can run one right
now by typing (run).  For further details, see the Users' Guide.

