
How to build planners and try them out:
=======================================

In the NewPlan directory do:

  % make

This will generate an executable planner called simplePlan in the
Planners directory.  To run it on a simple problem do:

  % Planners/simplePlan -m DomainModels/Rover/rover.ddl -i DomainModels/Rover/goToHillAndRock.init

More domains can be found in the DomainModels directory.

See near the end of this file for more make targets and a brief
description of all of the "user level" make variables.

The files/directories in this directory:
========================================

Copyright:
----------
  Copyright information.  Should be repeated at the start of each
file that is distributed.

README:
-------
  This file.  It describes the files and directories in the NewPlan
directory, and the modules and programs that are defined.


ConstraintNetwork:
------------------
  Directory contains the object source code needed to build the
Constraint Network class library.  It depends on the Library module,
the TemporalNetwork module, and on files in Includes.


DesignDocuments:
----------------
  Directory contains the latex source code for the design
documents for Europa and a PlannerTests text file containing a
brief overview of the implemented tests.

DomainModels:
-------------
  Directory that contains a selection of sample models.  Currently, it
includes a new version of the Remote Agent Experiment model, a simple
rover model, and a monkey-banana model.  Each of those models comes
with one or more initial states.


Includes:
---------
  Directory of all public include files in the system.


Libraries:
----------
  Directory containing a multitude of useful classes, including lists,
values, domains, sorts, and sets.  The classes are compiled together
into a library.  Most other system modules depend on this library.


ModelManager:
-------------
  Directory contains the object source code for the model manager,
which represents a model and provides information based on that.  It
depends on the Libraries.


ModelParser:
------------
  This directory contains the grammar files and the necessary source
code to build a parser capable of parsing model files, initial state
files, and heuristic files, and build (initialize) the appropriate
objects.  Depends on Libraries, ModelManager, TokenNetwork.


ModuleTests:
------------
  Directory containing module interface tests for most of the system
modules.  Each interface test is in a separate subdirectory.


Planners:
---------
  Directory containing a set of sample planners that use this system
to represent and solve planning problems.  They depend on the
SearchLibrary, the ModelParser, and the ModelManager.


SearchLibrary:
--------------
  Directory containing a number of useful classes and utility
functions for writing planners for this system.  Builds a search tool
library.


SupportFiles:
-------------
  Directory containing files that do not pertain directly to the
system, but support the coding effort.  Includes emacs setup files to
standardize indentation and tab-use.


SystemsTests:
-------------
  Directory containing a sequence of system tests, aimed at testing
the system incrementally, from the temporal network to the token
network.


TemporalNetwork:
----------------
  Directory containing the object source for the temporal network
class.  Depends on the Libraries.


TokenNetwork:
-------------
  Directory containing the object source code for the token network,
which represents the whole internal plan database.  The module depends
on ConstraintNetwork, Libraries, ModelManager, and Parser.


TokenTester:
------------
  Directory containing Lisp-code used in generating system tests.


UnofficialTests:
----------------
  Directory contains various components, examples and planners that
are being used for testing, but come with no guarantees.


commonMakeOptions.imake:
------------------------
  File containing options shared by all makefiles for the system.
The following make variables affect how the code is compiled.

DEBUG=0
	Compile without extra debugging information.  The default
	is to use -ggdb (g++) or -g (Sun's CC).

DEBUG=1
	(or any value except 0)
	Compile with extra debugging information (-ggdb or -g) plus
	-D_EUROPA_DEBUG_VALUE_=$(DEBUG), which allows varying levels
	of debugging output.

EUROPA_VERSION
	As distributed (via CVS or tar), this variable is not defined.
	Compiling when this variable is undefined produces the "normal"
	version.  Other versions are produced with the following values
	of EUROPA_VERSION:

    _EUROPA_DEBUG_VERSION_
    _EUROPA_FAST_VERSION_
    _EUROPA_NORMAL_VERSION_
    _EUROPA_NO_ERROR_CHECKS_

	Except for _EUROPA_NORMAL_VERSION_, which has no effect on
	compilation, these are also created as #define's for use with
	#ifdef, #if defined(X), etc.  The "fast" version mostly differs
	by ignoring type information in class Value, but there are
	"fast" versions of several others classes; see the '#ifdef
	_EUROPA_FAST_VERSION_' section of Includes/commonDefs.hh for the
	current list.  The "debug" version performs extra safety checks
	that are sometimes too slow for actual use, including checks
	that the normal and fast versions will produce the same results
	in all cases.  The "no error checks" version is just that: all
	error checks - calls to checkError(), handleError(), etc. in
	Includes/error.hh are #ifdef'd out.

PROFILE=1
	(or any value except 0)
	Compile with profiling code (-pg).
	Default is to compile without profiling.

OPTIMIZE=3
	(or any other value; only 0 thru 3 are likely to be useful)
	Compile with extra optimization (-O3, in this example).
	The default is to compile without optimization (which is
	quicker to compile, but produces slower programs).

SHARE=1
	Compiles using and producing shared libraries (*.so).
	The default is to compile with regular, "static" libraries (*.a).

YY_LETTERS=ww
	Compile the parser with 'ww' (for example) replacing all
	of the 'yy'-named functions and variables.  Can be any
	value that is appropriate for the start of C/C++ symbol names.
	Default is 'yy', equivalent to no (or an empty) value for this
	variable.

makefile:
---------
  The top level makefile.  To make the system, simply type:
    % make
  To make all test code, but not run it,
    % make test-code
  To make and run all official test code:
    % make tests
  To make and run all tests:
    % make everything

The make variables described just above can either be added to the
make command line, like:

    % make SHARE=1

... or added to the top of commonMakeOptions.imake itself (but be
careful not to commit such changes, or the defaults listed above will
be affected).
