## -*- Mode: Text -*- 
###############################################################################
## 
## File            : README
## Author          : Thomas McGinnis
## Created On      : Fri Jun 25 10:01:17 1993
## Last Modified By: Thomas McGinnis
## Last Modified On: Fri Jul  2 11:49:34 1993
## Update Count    : 5
## 
## PURPOSE
## 	To instruct people installing Soar6
## TABLE OF CONTENTS
## 	- How to unpack a .tar.Z file
##      - How to compile the Soar6 code
## 
###############################################################################
## Status          : Unknown, Use with caution!
## HISTORY
## 
###############################################################################


How to unpack a .tar.Z file:
  A file name that ends in .tar.Z indicates a compressed tar file.  To unpack
  this file, first put the file into a empty directory via the following:

     % mkdir <directory_name>
  where <directory_name> is where you want to compile the code.
  (NB: Throughout this text, any string surrounded by "<" and ">" is a
   variable, which you should replace appropriately and consistently as
   you work through these instructions.)

     % cp <filename>.tar.Z <directory_name>
  where <filename> is everything except for the .tar.Z part of the file.
  (i.e. 6.0.0g  if your .tar.Z file was named 6.0.0g.tar.Z)

     % cd <directory_name>
  You will now be in the directory where you are going to unpack the code.

  At your prompt type:

     % uncompress <filename>.tar.Z
  This will remove <filename>.tar.Z and produce a file named <filename>.tar

  Now at the prompt type:

     % tar -xvf <filename>.tar
  This will give you quite a bit of output as it unpacks each of the files
  in the archive.  When it is finished, you should have the following in
  the directory where you initially placed the .tar.Z file.
  a) The <filename>.tar file.
  b) A directory named 6.<X>.<Y> where <X> and <Y> are numbers.  This
     directory will have all the rest of the source code files below it.
  You can at this point remove the .tar file if you wish.

###############################################################################

How to compile the Soar6 code:
  cd into the directory created by unpacking the code in the previous step.
  In this directory, there will be a file named 'makefile'. I will refer to
  this file as the makefile from here on out.

  If you look at the contents of the makefile, you will see that it merely
  includes two other files: a header file (initially make.header.generic)
  and the file make.body . It (and the header and body files) also contain
  many lines that begin with "#" -- These are comments. They are ignored
  by 'make' but are there for you to read as a supplement to this text.

  a) Provided with the release are a number of files named make.header.<system>,
     e.g. make.header.hp, make.header.sun, et cetera. If one of these files
     is appropriate for your system, you should edit the makefile to include
     it instead of make.header.generic (the default).

  b) If neccesary, edit the make.header file you have chosen to invoke the
     C compiler for your system, i.e. change the line

       CC = gcc

     to be the appropriate compiler for your system.

     If the make.header you use defines a MACHINE_DEP_DIR, e.g. pmax_mach,
     make sure a directory by that name appears in each of the bin, convert,
     lib and obj directories (i.e. bin/pmax_mach, convert/pmax_mach,
     lib/pmax_mach and obj/pmax_mach). If these directories do not exist,
     you should create them, i.e.

      % mkdir bin/pmax_mach
      % mkdir convert/pmax_mach
      % mkdir lib/pmax_mach
      % mkdir obj/pmax_mach

  c) If you are adding any code (for IO or hooks) to the source code, place
     the .c source files into the user subdirectory of the Soar release
     directory (i.e. in .../6.<X>.<Y>/user).  You will only need to add code
     if you are creating new functions, or changing the abilities of current
     functions in the soar code.  If that is not your intent, you are most
     likely not adding any code.

  d) If you did not add any files to the user directory, go to step f.

  e) Edit the make.body file. For each file you added to the user subdirectory
     in step c, add that file to the line the begins with "USER_SRC =", e.g.
     if your files are user/my-io.c and user/my-hooks.c , you would change
     the line to:

       USER_SRC = ${USER_DIR}/my-io.c ${USER_DIR}/my-hooks.c

     You will also have to add entries to the "USER_OBJ =" line which appears
     shortly after the "USER_SRC =" line. This will look just the same except
     that the file names should end with .o instead of .c , e.g.

       USER_OBJ = ${USER_DIR}/my-io.o ${USER_DIR}/my-hooks.o

     If your code will require any other libraries to be linked, e.g. the
     math library, add the link directives to the
     "LIBS = ${SOAR_LIBS} ${EXTRA_LIBS}" line, e.g.

       LIBS = ${SOAR_LIBS} ${EXTRA_LIBS} -lm

     Finally, you must add a compilation command for each of your files.
     The easiest way to do so is to go to the end of the make.body and
     add entries like this (to continue the example):

       ${USER_DIR}/my-io.o: ${USER_DIR}my-io.c
               ${COMPILE.c} ${USER_DIR}/my-io.c

       ${USER_DIR}/my-hooks.o: ${USER_DIR}my-hooks.c
               ${COMPILE.c} ${USER_DIR}/my-hooks.c

     (NB: The second line of each of these entries must be intented by a
      TAB character (control-I, ASCII \011), not SPACES -- This is due to
      the nature of 'make'. For more information on this or other parts of
      make's nature (such as the ${<whatever>} notation}, see the man page
      for make).

  f) Type 'make' at your prompt.  This will create the soar executable
     and the convert program executable in the bin subdirectory (or in the
     bin/<MACHINE_DEP_DIR> subdirectory, if your make.header specified a
     MACHINE_DEP_DIR.) If you are using gcc as your compiler, ignore any
     warnings that appear during this step.

  g) Finally, make sure the soar executable is in your PATH so you can run
     it. You can either add .../6.<X>.<Y>/bin/<MACHINE_DEP_DIR> to your
     PATH, or you can copy the soar executable from there to a more likely
     place (e.g. /usr/local/bin).

How to get help if things don't work:
  If you follow these steps, and things do not work correctly for you, you
  should report the problems to soar-bugs@cs.cmu.edu.

How to use the Soar program and the convert program:
  The convert program has its own README file which can be found in the
  subdirectory named convert.  Read this file to learn how to use the convert
  program.

  To run both the convert program and the soar program, you should (assuming
  the steps above to install it worked) be able to just type the name of
  the program (along with any arguments) on the command line.

Soar6 default rules:
  The standard set of soar 6 default rules exists in the subdirectory 
  default.

Testing:
  If you want to run the regression test code that we use for testing code
  changes to make sure everything installed correctly, change directory into
  the tests subdirectory and execute the run-all-tests shell script.

  If you are running the multi-agent version you can test that as well
  by compiling with MULTI_AGENT_ENABLED and without USE_X_DISPLAY.
  This option is indicated in the make.body file.  Once compiled, you
  can cd to tests/multi/multi and execute the file "run-multi-test".
  If you want to simply see the test run rather than compare it to 
  the benchmark, then simply type "soar" in the same test directory.
