
                                 Volume II
                                 ------ --

                         Khoros Programmer's Manual
                         ------ ---------- - ------

                                 Chapter 10

                             INSTALLATION GUIDE

                  Installation Guide for the Khoros System

                             Primary Author(s):

                                 John Rasure
                                 ---- ------

                  c
        Copyright   1992 University of New Mexico.  All rights reserved.

                          Printed: March 16, 1992


        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

                                  CONTENTS

        Chapter 10 - INSTALLATION GUIDE

        A.  INTRODUCTION ......................................    1

              A.1  PREREQUISITES ..............................    1

              A.2  OTHER DOCUMENTATION ........................    2

              A.3  SUPPORT AND MAINTENANCE ....................    3

              A.4  COMMON PROBLEMS ............................    3

        B.  KHOROS VIA FTP DISTRIBUTION .......................    4

              B.1  ACQUIRE TAR FILES ..........................    4

              B.2  COMMON PROBLEMS IN ACQUIRING THE SYSTEM ....    5

              B.3  UNTAR THE FILES ............................    6

              B.4  COMMON PROBLEMS IN UNTARRING FILES .........    7

        C.  KHOROS VIA TAPE DISTRIBUTION ......................    7

              C.1  EXTRACTING KHOROS FROM TAPE ................    7

        D.  CONFIGURING YOUR ENVIRONMENT ......................    7

              E.  COMPILING KHOROS ............................    8

                   E.1  CONFIGURING THE IMAKE SYSTEM ..........    9

              E.1.1  Commonly Asked Questions About
        Configuring Imake .....................................    9

              E.2  STARTING THE COMPILE .......................   11

              E.3  COMMON PROBLEMS WITH COMPILING .............   12

        F.  INSTALLING TOOLBOXES ..............................   12

        G.  GETTING STARTED ...................................   13

        KHOROS                  Release: 1.0                  10 - i


        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

                             INSTALLATION GUIDE

        A.  INTRODUCTION
        -   ------------

             Welcome to Khoros 1.0 (Patch 5)!   This  document  con-
        tains  the information that you need to load and install the
        Khoros software onto your system.  Both source and  binaries
        are  available  via  anonymous ftp or by ordering a tape and
        printed documentation.

        The installation procedure outline follows:

             Step  1)   ftp  from  pprg.eece.unm.edu  or  order  and
                       receive a tape

             Step 2)   untar  the  source  and/or  binary  files  in
                       KHOROS HOME
                             -

             Step 3)   set up your user environment

             Step 4)   if you did NOT install binaries and  want  to
                       compile, run installit

             Step 5)   read Volume 1, Chapter 1 of the Khoros manual
                       and try Khoros out!

        A.1  PREREQUISITES

        If you are going to use the binaries provided (sun4, sgi, or
        dec  mips), then the prerequisite is to have some version of
        the the X windows system and  about  40  Megabytes  of  disk
        space  plus  the  amount  of  space needed for binaries (see
        table below).

        The following list of prerequisites is for those  that  plan
        on compiling the system.

        +    X11R4 or X11R5 from MIT with current patches.  You need
             X11R4  or  X11R5 libraries (client libraries, X11, Xaw,
                                                           ---  ---
             Xt, Xmu and  Xext)  to  compile  Khoros;  however  once
             --  ---      ----
             Khoros  is  compiled, it will run with an X11R3 server.
             Both X11R4 and X11R5 are available  via  Anonymous  FTP
             from "export.lcs.mit.edu".

        +    A C compiler

        +    A Fortran compiler is recommended (not  all  of  Khoros
             will be available without a Fortran compiler)

        KHOROS                  Release: 1.0                  10 - 1

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

        +    The compress program (available via Anonymous FTP  from
             "pprg.eece.unm.edu").

        +    About 65 Megabytes of disk space plus room for objects,
             libraries and binaries (see table below)

        
        ------------------------------------------------------------
        |Khoros 1.0 Binaries Are Available for These Architectures  ||
        ++----------------------------------------------------------||
        Vendor |Name      OS            |.o's and lib|Binaries (Meg)
        ||                                                          ||
        -------+----------+-------------+------------+--------------
        DEC     5000/3100 Ultrix 4.1               37             66||
               |          |             |            |
        SUN     sparc     SUN OS 4.1.1             21             63||
               |          |             |            |
        SGI     Indigo    OS 4.0                   36             70||
        ||     |          |             |            |              ||
        ------------------------------------------------------------

        A.2  OTHER DOCUMENTATION

             If you are unsure about the installation of Khoros  and
        need  additional information, the following documents may be
        of help:

        khoros    This is a four page overview of  Khoros.   If  you
                  are  not  sure  what Khoros is and what it can do,
                  read this document to get a better  overview  than
                  the one provided in the announcement. This file is
                  located in $KHOROS HOME/release.
                                    -

        chapter1  Volume I, Chapter 1 of the  Khoros  User's  manual
                  provides  general information for the Khoros user.
                  This should be considered required reading.

        chapter9  Volume II, Chapter 9 of  the  Khoros  Programmer's
                  Manual  provides  a  detailed  description  of the
                  source configuration  and  imake  system  used  by
                  Khoros.   This  will  be  helpful to those who are
                  porting the software to other architectures or are
                  having trouble with compiling.

        appendixB Volume II, Appendix C of the  Khoros  Programmer's
                  Manual  provides  a  detailed  description  of the
                  imake system symbols and rules. This  document  is
                  helpful when modifying the Khoros imake system.

        announce  This  is  the  announcement  of  the  Khoros   1.0
                  release.   It  provides a brief overview of Khoros
                  and ordering information.  This file is located in
                  $KHOROS HOME/release.
                         -

        This document, install, and the documents listed  above  are
        available   in  both  postscript  and  plain  text  form  on
        pprg.eece.unm.edu in the directory pub/khoros/release or  in
        your   copy  of  Khoros  in  $KHOROS HOME/release.  A  *.ftp
                                            -
        indicates that it is a plain text  file,  a  *.ps  indicates

        KHOROS                  Release: 1.0                  10 - 2

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

        postscript (ready to print), and a *.ms indicates that it is
        the source "roff" file. Instructions on how to obtain  these
        files is provided below.

        A.3  SUPPORT AND MAINTENANCE

             Even though many users of Khoros have said that  it  is
        quality  software,  Khoros  1.0 is not a commercial product.
        Support   is   provided   via   an   e-mail   users    group
        (khoros@chama.eece.unm.edu),  a USENET news group comp.soft-
        sys.khoros, and periodic updates. To join the Khoros mailing
        list,  mail to khoros-request@chama.eece.unm.edu.  To report
        bugs, mail to  khoros-bugs@chama.eece.unm.edu.   Please  use
        the bug report form found in $KHOROS HOME/repos/BugReport as
                                            -
        a template for reporting bugs.

             There are several  companies  that  are  likely  to  be
        selling  Khoros  support in the near future.  Please inquire
        if you are interested.

        A.4  COMMON PROBLEMS

             Khoros 1.0 is a large system, and  often  an  end  user
        only  wants  part of its functionality.  This often leads to
        complaints about the system requirements.  The only solution
        to  this  problem  now is to obtain Khoros as it is, install
        it,  and then delete the components of the system  that  you
        do  not  want.  The minimum set of directories that you need
        to run Khoros are:

        bin       contains executables

        repos     User Interface Specification files,  architecture-
                  specific configuration files
                  You may also want to keep:

        doc       Online help

        man       man pages used by vman

        manual    contents of printed manual

        release   starter documentation

        data      example data
                  You do not need the following for only a "runable"
                  Khoros system:

        src       needed for compiling

        lib       needed for compiling

        include   needed for compiling

        KHOROS                  Release: 1.0                  10 - 3

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

        B.  KHOROS VIA FTP DISTRIBUTION
        -   ------ --- --- ------------

             First you must determine where on your system that  you
        want to install Khoros and then create a directory (any name
        is fine).  This  can  be  done  by  creating  a  user  named
        "khoros",  or  simply  by  creating a home directory such as
        /usr/local/khoros or /usr/khoros.

        B.1  ACQUIRE TAR FILES

        Move to the directory that you just created and then execute
        the  following commands to acquire the Khoros compressed TAR
        files.

             a.   Use ftp to connect to pprg.eece.unm.edu.
                  % ftp pprg.eece.unm.edu
                       -or-
                  % ftp 129.24.24.10

             b.   Use "anonymous" or "ftp" as the user name.
                  Name (pprg.eece.unm.edu:login): anonymous
                       -or-
                  Name (pprg.eece.unm.edu:login): ftp

             c.   Use your e-mail address as  the  password;  please
                  use  a valid e-mail address, as this ftp site logs
                  all anonymous ftp's.
                  Password (pprg.eece.unm.edu:user): {your valid  e-
                  mail address}
                  331 Anonymous login ok, use your E-MAIL address as
                  the password.
                  230 Guest login ok, access restrictions apply.

             d.   Get the  installation  guide  (this  file,  called
                  install.ftp)  for  acquiring  Khoros via anonymous
                  ftp.  (note that "install.ftp" is the  plain  text
                  file  -  both  ".ms" and ".ps" files are available
                  for those who would like them).
                  ftp> cd /pub/khoros/release
                  ftp> get install.ftp

             e.   Set the ftp program to binary mode.
                  ftp> bin

             f.   The next step is to actually get  the  Khoros  TAR
                  files.   The  compressed  TAR files are located in

        KHOROS                  Release: 1.0                  10 - 4

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

                  four  separate  directories:  bins   (sun4,   sgi,
                  decmips), system, source and data.  Within each of
                  these  directories,  you  will   find   both   the
                  compressed  TAR  file  and  a set of "split" files
                  created from  that  TAR  file.   You  can  have  a
                  functional  Khoros  system  without  the  data and
                  system directories,  in  other  words,  a  minimal
                  system can be installed with only system and bins.

                  To get the system directory:
                  ftp> cd system
                  ftp> get system.tar.Z

                  The  system.tar.Z  has  been   split   into   many
                  different  files;  if you have trouble getting the
                  system.tar.Z file, you may try getting each of the
                  split  files  individually.  To  use  this method,
                  substitute the previous commands with:

                  ftp> prompt
                  ftp> mget system.[0-9]*

             g.   In the above steps, you acquired the  "foundation"
                  (doc,  dotfiles,  repos,  man, manual, release) of
                  the Khoros system. In order to  get  bins,  source
                  (src  and  include) and data, go to that directory
                  on pprg.eece.unm.edu and  follow  the  same  basic
                  steps  as  above.  A minimal system can be created
                  by only obtaining the system and bins directories.

        B.2  COMMON PROBLEMS IN ACQUIRING THE SYSTEM

             It is not uncommon for the files to be corrupted during
        ftp  transfer.   To verify that you have good files, use the
        *.listing file found in each directory of  pprg  along  with
        the  TAR  files.  Check to see that the calculated checksums
        match.   For example,  if you  got  the  system.tar.Z  file,
        this   procedure   will   be   simple.    First,   get   the
        "system.listing"    file    from    pprg.eece.unm.edu,    in
        /pub/khoros/system,  if you have not already done so.  Then,
        run:

             % sum system.tar.Z

        The output of the sum program  should  match  the  statistic
                          ---
        given  for  system.tar.Z,  at  the top of the system.listing
        file.  If it does not match, this  indicates  that  the  TAR
        file   has  been  corrupted.   If  the  TAR  file  has  been
        corrupted, you may want to re-acquire the system as detailed
        in  the  previous section.  Or, you can find out which files
        are bad by executing:

        KHOROS                  Release: 1.0                  10 - 5

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

             % zcat system.tar.z | tar tvf - > my system.listing
                                                 -

        Now, execute:

             % diff system.listing my system.listing
                                     -

        This will list the differences between the  two  files.   Of
        course,   the   first   ~30   lines   will  differ,  as  our
        system.listing file has additional checksum  information  at
        the  beginning;   however, if any other lines in the listing
        differ,  look at the filenames  listed  on  the  lines  that
        differ.  This will indicate which files were corrupted.

             If you got the split files, it is best to write a small
        "foreach" script to perform the checking procedure for you.

        B.3  UNTAR THE FILES

             You have already created a "home" directory for the TAR
        files,   now   you   must   set   the  environment  variable
        KHOROS HOME.  It should be set to the  home  directory  that
              -
        you  created  above.  For  instance,  if  you created a home
        directory /usr/khoros,

             % setenv KHOROS HOME /usr/khoros
                            -
                   or

             % setenv KHOROS HOME ~khoros
                            -

             if you set up a user name for Khoros.

        All of the TAR files should be untarred in  the  KHOROS HOME
                                                               -
        directory.  (In the case of untarring binaries for more than
        one architecture, you may want to create a binmach directory
        and untar the bins into different subdirectories.)  To untar
        the system.tar.Z file, use the following commands:

             % cd $KHOROS HOME
                         -

             % zcat system.tar.Z | tar -xfoB -
                                      -OR-
             % uncompress -c  system.tar.Z | tar -xfoB -

        If  you  transferred  the  split  files   instead   of   the
        system.tar.Z file, you will need to do:

             % cd $KHOROS HOME
                         -
             % cat system.[0-9]* | uncompress > system.tar
             % tar -xf system.tar

        Alternatively, you may use (WARNING: this is not as reliable
        and doesn't seem to work on bindecmips):

        KHOROS                  Release: 1.0                  10 - 6

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

             % zcat system.[0-9]* | tar -xfoB -
                                      -OR-
             % uncompress -c system.[0-9]* | tar -xfoB -

        You should follow the same basic  procedure  for  the  data,
        source  and  bins  TAR files. After you untar the compressed
        TAR file, you may want to remove the TAR file to save space.

        B.4  COMMON PROBLEMS IN UNTARRING FILES

             Be sure that you have not run  out  of  disk  space  by
        using  the  %df  .   command.   If you run out of disk space
        during the untarring procedure, the untarred  Khoros  system
        will  be  corrupted.  Delete the untarred Khoros system, and
        free up some  extra  space  before  starting  the  untarring
        procedure  again.  Often, an uncompressed TAR file gets left
        around after it is successfully untarred; delete it to  free
        up additional space.

        C.  KHOROS VIA TAPE DISTRIBUTION
        -   ------ --- ---- ------------

             First you must determine where on your system that  you
        want to install Khoros and then create a directory (any name
        is fine).  This  can  be  done  by  creating  a  user  named
        "khoros",  or  simply  by  creating a home directory such as
        /usr/local/khoros or /usr/khoros.

             The tape  distribution  includes  tape(s)  with  Khoros
        source  and binaries (if ordered), Volume one and two of the
        Khoros manual and installation instructions  for  extracting
        Khoros from the tape(s).

        C.1  EXTRACTING KHOROS FROM TAPE

             Your tape distribution should include  instructions  on
        how to extract Khoros from the tape(s). If you have problems
        with extracting Khoros off the tape(s), please  contact  us.
        Note,  make  sure  you  move  to the directory that you just
        created before extracting Khoros from tape.

             If you did not receive  binaries  or  want  to  compile
        Khoros  on  another  architecture,  follow  the instructions
        below for compiling Khoros.

        D.  CONFIGURING YOUR ENVIRONMENT
        -   ----------- ---- -----------

             You will need to set up your user environment  so  that
        Khoros applications will run properly.  The files of concern
        are: .cshrc or .login, .khoros env and .Xdefaults.   If  you
                                      -

        KHOROS                  Release: 1.0                  10 - 7

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

        need  more  details than what is provided below, please read
        Chapter 1, Volume 1 on "Getting Started" with Khoros.

             Provided  with  the  release  is  a  directory   called
        "dotfiles" that provides templates or examples for the files
        mentioned below.

        .cshrc      Modify your ".cshrc" or ".login" file to include
                    a  path  to  $KHOROS HOME/bin.   The ".cshrc" or
                                        -
                    ".login" file should source .khoros env.
                                                       -

        .khoros env The environment variables used by Khoros are set
               -
                    in   the   .khoros env   file.    Use  the  file
                                      -
                    $KHOROS HOME/dotfiles/khoros env as a template.
                           -                    -

                    % cp dotfiles/khoros env .khoros env
                                        -           -

        .Xdefaults  Use the one provided to start  with;  it  is  in
                    $KHOROS HOME/dotfiles/Xdefaults.
                           -

                    % cp dotfiles/Xdefaults .Xdefaults

                    As a note, Khoros was developed using  primarily
                    the twm window manager which is distributed with
                    X11R4.   To  test  out  your  new   environment,
                    execute the following commands:

                    % source .cshrc

                    % xrdb .Xdefaults

             If you have obtained and  untarred  binaries,  you  can
        skip  the following section on compiling Khoros. However, it
        is very important that you execute the following program  to
        configure the man pages for your site:

             % $KHOROS HOME/man/utils/tmac/customize
                      -

        If you forget to run the customize program, the vman command
                                 ---------
        will  not  work,  and you will not have access to the Khoros
        man pages.

        E.  COMPILING KHOROS
        -   --------- ------

             If you have all of the prerequisites as  stated  above,
        and you are compiling for one of the platforms listed above,
        the configuration should be quite simple.  However,  if  you
        are  compiling  for a new (unsupported) architecture or want
        to  support  multiple   architectures,   you   should   read
        $KHOROS HOME/release/chapter9             and            use
               -
        $KHOROS HOME/release/appendixB  as  a  reference  for  imake
               -

        KHOROS                  Release: 1.0                  10 - 8

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

        changes.  You  should be most concerned with configuring the
        Khoros imake system correctly. If  you  received  a  printed
        manual consult Volume II, Chapter 9 and Appendix B.

        E.1  CONFIGURING THE IMAKE SYSTEM

             Before starting the compile,  the  imake  configuration
        files   in   $KHOROS HOME/repos/config/imake conf   must  be
                            -                       -
        modified.  The  files  that  need  special  attention   are:
        platform.cf,  where platform is the name of the architecture
        -------- --         --------
        (i.e. for a Sun use sun.cf, for  a  DecMips  use  ultrix.cf,
        etc)  and  Site.def.  The symbol defines in these files need
        to be set according to how you want to compile  Khoros.  For
        example,  if  your  system does not have a Fortran compiler,
        the symbol "HasFortran" in the platform.cf file  must be set
                                       -------- --
        to "NO".

             We have tried to tailor the imake  configuration  files
        so  that  very  little  effort  is needed to compile Khoros,
        however, it is important that  you  check  these  files  for
        correctness.   While  the  imake configuration files such as
        platform.cf and Site.def are  fairly  well  commented,  more
        -------- --     ---- ---
        information  can be found in Chapter 9 and Appendix B.  Once
        the imake configuration files have been  modified,  you  are
        ready to compile Khoros.

        E.1.1  Commonly Asked Questions About Configuring Imake

             Below are a few  commonly  asked  questions  about  the
        imake  configuration  files.  If  you need to use any of the
        following symbols or any other imake symbol, we suggest that
        the symbol defines are put in the platform.cf file.
                                          -------- --

             Q:   X11 directories are not in the "standard" place on
                  my  machine,  how  do  I  specify  where  the  X11
                  directories exist?

             A:   define the symbol "XLibDir" to the directory where
                  the X11 libraries exist

                       #define XLibDir /usr/local/lib/X11

                  define the symbol  "XIncludes"  to  the  directory
                  where the X11 include directory exists.

                          #define XIncludes -I/usr/local/include

             Q:   Fortran libraries are in /usr/lang rather than  in
                  /usr/lib,  how  do  I  change  where  to  look for
                  Fortran libraries?

             A:   define the symbol "FortranLibDir" to the directory

        KHOROS                  Release: 1.0                  10 - 9

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

                  where the Fortran libraries exist

                       #define FortranLibDir /usr/lang

             Q:   I need to add  some  other  libraries  to  compile
                  against, how do I add these extra libraries?

             A:   define the symbol  "ExtraLibs"  to  the  directory
                  where the libraries exist

                       #define ExtraLibs /myhome/foobar

             Q:   How do I make the libraries load with a  different
                  option than the C programs load with?

             A:   define the symbol "LibraryLdCmd"  to  the  command
                  that  you  want the libraries to load with and the
                  "LdCmd"  to  the  command  that  you  want  the  C
                  programs to load with.

                       #define LibraryLdCmd ld
                       #define LdCmd cc

             Q:   How do I specify  different  compile  options  for
                  libraries and C programs.

             A:   define  the  symbol  "LibraryCCOptions"   to   the
                  options  that  you  want  the libraries to compile
                  with and the  "DefaultCCOptions"  to  the  options
                  that you want the C programs to compile with.

                       #define LibraryCCOptions -q -P
                       #define DefaultCCOptions -float

             Q:   How do I specify  different  compile  options  for
                  Fortran libraries and Fortran object files.

             A:   define  the  symbol  "LibraryFCOptions"   to   the
                  options  that  you  want  the  libraries  or other
                  Fortran object files to compile with.

                       #define LibraryFCOptions -O

             Q:   I can not regenerate the Khoros manual  on  a  Sun
                  Workstation  because  soelim  for .so lines in the
                  roff  files,  limits  the  file   length   to   64
                  characters.

             A:   This is a bug and has been reported  to  Sun,  but
                  not  expected  to be fixed until the release after
                  4.1.2 (maybe). We are distributing a public domain
                  version  of  the  soelim program.  If you think or
                  know that your OS has this problem, then make sure
                  you have the following symbol set to YES.

        KHOROS                  Release: 1.0                 10 - 10

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

                       #define SoeLim YES

             Q:   Can I compile Khoros and utilize shared libraries.

             A:   As of Patch 5 we are only  supporting  Sun  shared
                  libraries.  We  have  the  mechanisms in place for
                  other architectures, but  have  not  verified  the
                  shared  rules. If you want to compile the Sun with
                  Shared   Libraries    then    set    the    symbol
                  "HasSharedLibraries" to YES.

                       #define HasSharedLibraries YES
                  If you want to port Khoros to use shared libraries
                  on  your  architecture,  you should model it after
                  the the Sun  version.  You  will  have  to  either
                  modify  or  create  a  library  rules  file in the
                  $KHOROS HOME/repos/config/imake conf/Lib.
                         -                       -

             Although many  more  questions  about  configuring  the
        imake  system  have  been  asked,  this set of questions and
        answers should give one the feel of how to make  changes  to
        the  imake  configuration  files.   It is strongly suggested
        that the document Volume 2, Appendix B, "Imake  Symbols  and
        Variables"  be  consulted  when  making changes to the imake
        symbols.

        E.2  STARTING THE COMPILE

             The installit program in $KHOROS HOME/src  will  prompt
                                             -
        you  for  some  default  directories and startup flags.  The
        installit program will modify the  imake  Site.def  file  to
                                                  ---- ---
        include  the correct location for Khoros binary, library and
        include  directories.   To  compile  Khoros,   execute   the
        following commands:

             % cd $KHOROS HOME/src
                         -
             % ./installit

        If you would like to watch the compile, you can execute:

             % tail -f make.World

        Note that if you use the "tail" command to watch the  Khoros
        system  compile,  you  will  have to "^C" out of it when the
        compile has been completed.

        The compile will take several hours.  Some typical times are
        listed below.

                SparcStation 1        5 hours (src mounted on NFS partition)
                Sun3/260              4.6 hours (using gcc on NFS partition)
                Vax 3500              4.4 hours (using cc  on NFS partition)

        KHOROS                  Release: 1.0                 10 - 11

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

                DecStation 5000       3.33 hours (local disk)
                SGI Indigo            2.00 hours (local disk)

        E.3  COMMON PROBLEMS WITH COMPILING

        Again, the most common problems is that you run out of  disk
        space  or  NFS  will  time  out during the compile.  If this
        happens, you should:

             % cd $KHOROS HOME/src
                         -
             % make allclean; installit

        The reason that you need to "clean" the system is because of
        the possibility of corrupted .o's and libs.

             It is not unusual to have a system failure  (NFS  dies,
        machine  crashes,  etc) during the compile.  Follow the same
        instructions as above.

             If the "installit" fails due to compile errors,  please
        verify  that  you  have  configured  the  imake system files
        located in  $KHOROS HOME/repos/config/imake conf  correctly.
                           -                       -
        Consult Volume II, Chapter 9 for assistance.

        F.  INSTALLING TOOLBOXES
        -   ---------- ---------

             This section discusses how to install  a  toolbox  that
        was  created  by  another person or was developed on another
        machine, and is being set up on a new machine.  Note, It  is
        assumed that Khoros is already installed at this point.  The
        following steps must be followed  in  order  to  update  the
        configuration files for the new directory and machine.

        1.   Set the environment  variable  KHOROS TOOLBOX  to  your
                                                  -
             toolbox file.  To do this type the following command.

                  % setenv KHOROS TOOLBOX {Pathname to Toolbox file}
                                 -

        2.   Find a  location  for  your  toolbox,  and  create  the
             directory.    If   you   received   Khoros   via   tape
             distribution, then follow the installation instructions
             you  received  with  your  order.   Otherwise,  If  you
             aquired the toolbox via ftp, the file will  be  in  tar
             format.   To  untar  the  toolbox,  use  the  following
             command:

                  % tar -xf {toolbox tar filename}

             Make sure you cd to the directory you want to unpack it
             to, before typing the untar command.

        KHOROS                  Release: 1.0                 10 - 12

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

        3.   For the rest of this discussion, {top dir}  will  refer
             to  the  directory  that contains the top level of your
             toolbox.            Modify           the           {top
             dir}/repos/config/src conf/{toolbox} mf file.  Look for
                                  -              -
             the KHOROS USER tag inside  the  file,  and  substitute
                       -
             your user name for one that is already there.  Use \pwd
             in the toolbox/src directory to get the absolute  path,
             and  replace the path assigned to the LOCAL SRC TOP tag
                                                        -   -
             with this new path.

        4.   Run kraftsman to add the toolbox entry to your  toolbox
             file.   (See  the  help page on "ADD TOOLBOX" option on
             the "Creation" pane in kraftsman, or check in Volume 2,
             Chapter  11  for information on how to add a toolbox to
             your toolbox file.)

        5.   After adding the toolbox entry to your toolbox file, go
             to  the  "Configuration"  pane, and make sure that both
             the Binary Path and Library Path are correct.  (See the
             configure  toolbox  documentation  in Volume 2, Chapter
             11.)  Once you have set these paths correctly, you  may
             exit kraftsman.

        The rest of  the  instructions  explain  how  to  build  and
        install all the routines in the newly installed toolbox.

        6.   execute:
             % cd {top dir}/src

        7.   execute:
             % make Makefile Makefiles

        8.   execute:
             % make install

        Finally, you will need to add {top dir}/bin to your path  so
        that you will be able to execute the routines.  You may want
        to do this in your ".cshrc" file, so that you will not  have
        to remember to set the path every time you log in.

        G.  GETTING STARTED
        -   ------- -------

             Now that you have Khoros installed, you  will  want  to
        use  the  manual  printing  utility, prnmanual, to print out
        Volume 1, Chapter 1, "Getting Started", and other documents.
        If  you  received  a printed copy of the manual, there is no
        need to reprint any of the manual.

             Questions,  comments,  constructive  criticism  can  be
        mailed     to     the    Khoros    E-Mail    Users    Group,

        KHOROS                  Release: 1.0                 10 - 13

        Volume II  -  Programmer's Manualr 10  -  Installation Guide
        ------ --  -  ------------ ------

        khoros@chama.eece.unm.edu, or the Khoros USENET news  group,
        comp.soft-sys.khoros.   To  join  the  e-mail group, mail to
        khoros-request@chama.eece.unm.edu.  PLEASE: only requests to
                                            ------
        get  on  or  off  the  Khoros mailing list should go to this
        address.  Other mail is  very  likely  to  get  lost  or  be
        deleted.

             Once you are a member of the Khoros  Users  Group,  you
        may  mail any questions that are not addressed in the Khoros
        Manuals to khoros@chama.eece.unm.edu.  If a  member  of  the
        Khoros group itself cannot answer your question immediately,
        it is likely that another Khoros user may be able to.

             As with any system approaching the size of  the  Khoros
        system,  you  can  expect to find some bugs.  We already are
        aware  of   several   bugs;    these   can   be   found   in
        $KHOROS HOME/repos/BugList.  If you find a bug in the Khoros
               -
        system, please look through this file first to see if it  is
        one  of  the  bugs  that  we  already  have on our list.  We
        strongly encourage you to report any bugs that you may  find
        --------
        that  are  not  listed  in  the BugList.  All bugs are to be
        reported via email, to khoros-bugs@chama.eece.unm.edu.  When
                     -----                                      ----
        reporting   bugs,  please  include  the  version  of  Khoros
        ---------   ----   ------  -------  ---  -------  --  ------
        (located  in  the  file  $KHOROS HOME/src/Patchlevel),   the
         -------  --  ---  ----   ----------- --- ----------     ---
        machine  type  (execute:  uname  -a), and how the bug can be
        -------  ----   -------   -----   -   --- --- --- --- --- --
        duplicated.  You  can  send  us  Cantata  Workspaces  and/or
        ----------   ---  ---  ----  --  -------  ----------  --- --
        Journal Playback files.
        ------- -------- -----

             We hope that you like the Khoros system!

        KHOROS                  Release: 1.0                 10 - 14

