.\" @(#)installation	1.12 12/17/92
.EQ
delim off
.EN
.H1 "Installation"
.pp
\*(PT is a large software system that relies on a properly configured
software environment.  There are many things that can go wrong
in getting \*(PT running.  For instance, the windowing system may
not be the same one we use, or it may be used in a different way.
There is also some configuration required by each user in order to
use the graphical interface.  The information for doing this
is given in the Pigi document, section 2 of the Almagest.
Here we give the basic information required to get from an FTP
archive or distribution
tape to being able to run the system.
.H2 "Basic \*(PT installation"
.pp
First note that the
approximate disk space requirements are (for the Sun-4 distribution;
other distributions are roughly the same size):
.(b
	\*(PT: 49 Mbytes
	\*(PT (after you optionally remake): 64 Mbytes
	Gnu subset: 16 Mbytes
.)b
.pp
Create a user ``ptolemy'', together with a home directory for the ``ptolemy''
user.  
Once the "ptolemy" user account has been created, log in or
su to user ``ptolemy''.
If you do not wish to create a user called ``ptolemy'', 
see below for an alternative.  
.lp
If you are loading Ptolemy from a tape, do the following:
.ip a.
cd /tmp
(or any directory where you have write permission
and there is at least 22 Mbytes of free disk space).
.ip b.
Load the tape into your drive
.ip c.
mt -f /dev/nrst8 rewind
.br
(This rewinds the tape -- change the device name if your tape drive
has a different name.)
.ip d.
tar xf /dev/nrst8
.lp
If you have used FTP to down load the files, then
cd to the directory that contains the "*tar.Z" files you downloaded
via FTP.
.lp
Now, whether you've used tape or FTP,
there should be a number of large "*tar.Z" files in your current directory.
Proceed as follows:
.ip 1.
zcat pt-0.4.doc.tar.Z | ( chdir ~ptolemy/..; tar xf - )
.br
(this uncompresses the documentation, changes directory the parent of the
"ptolemy" user, and then creates all of the documentation files.)
.ip 2.
zcat pt-0.4.src.tar.Z |  ( chdir ~ptolemy/..; tar xf - )
.br
(this uncompresses the src and creates the source files.)
You must not skip this step.  \*(PT depends on these files being present.
Note that you may get a few warning messages during this and the following
step about
the tar program not being able to create some directories because they
already exist.  This is expected (the same directory is mentioned in
several of the tar files), so you need not worry. 
.ip 3.
If you are running the DecStation (MIPS) version of \*(PT:
.br
zcat pt-0.4.mips.tar.Z |  ( chdir ~ptolemy/..; tar xf - )
.br
If you are running the Sun 4 (Sparc, IPC, IPX, etc) version:
.br
zcat pt-0.4.sun4.tar.Z |  ( chdir ~ptolemy/..; tar xf - )
.br
(this uncompresses the binaries and creates the executable files.)
Note that is possible to install both the Sun-4 and the DecStation
binaries on the same file system as different directories are used for each
set of binaries.
.ip 4
cd "~ptolemy"
.br
(change directories to the ptolemy root directory)
.ip 5.
Edit ~ptolemy/.rhosts, adding a line for your system
(This gives pigi permission to create an RPC server process with the
.i rsh
command ).
The added line will be of the form "hostname ptolemy", you can
find the correct hostname with the Unix command "hostname".
Users will also need entries in their .rhosts files to allow
the server process to start up.
.H2 "Installation without creating a ``ptolemy'' user"
.pp
The preferred installation technique, as indicated above, is to create
a user called ``ptolemy''.  The reason for this is that running Ptolemy
requires an appropriate user configuration.
At minimum, the user's path must be set up properly.
The ``ptolemy'' user is also configured to run an X window manager
(twm) with suitable X resources that are known to work.
In troubleshooting an installation, having the ``ptolemy'' user
properly configured can be very valuable.
.pp
However, we recognize the some sites resist the creation of fictitious
users.  Consequently, Ptolemy can be installed anywhere.
If you do this, \fIevery\fR Ptolemy user must set a PTOLEMY
environment variable to point to the root directory of Ptolemy.
The installation is the same as above, except that ``~ptolemy''
is replaced with ``$PTOLEMY''.
.H2 "Special considerations for installation under Open Windows"
.pp
\*(PT was developed using the X11R4 or X11R5 distributions from MIT.  It will
run successfully under Open Windows version 2.  There are problems
with running the graphic interface with Open Windows version 3, however.
Some users have had no problems at all, but others have 
had intermittent
problems such as "bad match" errors.  We believe this may be a
problem with the X-server supplied with the Open Windows 3.0, but
the error is elusive and we have not yet tracked it down.
.pp
In order for all utilities included with this distribution to work
under Open Windows (either version), you must install the shared libraries
for the Athena
widgets (the freely redistributable widget set from the MIT X11 distribution),
which are provided with this distribution under the ``~ptolemy/athena.sun4'' 
directory.
To install them, become root
and copy all files in that directory into ``/usr/openwin/lib'' (or, if
.EQ
delim ##
.EN
you have installed Open Windows in a non-standard place, into ``$OPENWINHOME/lib'').
.EQ
delim $$
.EN
If you do not wish to do this, you could leave them in place and have
every Ptolemy user change their LD_LIBRARY_PATH environment variable
to search ``~ptolemy/athena.sun4'' before ``/usr/openwin/lib''.  Consult
the Unix manual entry for the ``ld'' program to learn more about this.
.pp
After installation, the ptolemy account will contain several scripts for
starting up X11R5 (Xrun), Open Windows with
.i olwm
(Xrun.ow),
or Open Windows with
.i twm
(Xrun.ow.twm).
.H2 "GNU Installation"
.pp
For convenience, some software from the Free Software Foundation is
included on the distribution tape.  This includes the compiler
used to make \*(PT, which is also the compiler you will use to extend
\*(PT.  Note that this is not a complete set of Gnu software.
.(f
It is also possible to build \*(PT with Sun's port of AT&T's
.i cfront
compiler, version 2.1.  To do so, you must completely rebuild Ptolemy.
The libraries on the tape were produced by the Gnu C++ compiler and
are not interoperable with
.i cfront
code.
.)f
.pp
To install the ptolemy gnu subset, proceed as follows:
.ip 1.
cd /usr/tools
.ip 2.
Check to see if there is already a "gnu" directory.  If so, you
probably don't want to load the ptoelmy gnu files here and should
pick a different location for the ptolemy gnu subset (be especially
careful in step 6 below).
If there is not already a "gnu" directory, then do the following command:
.br
mkdir gnu
.ip 3.
If you have \*(PT on tape, then do the following:
.ip a.
cd /tmp
(or any directory where you have write permission
and there is plenty, many Mbytes, of free disk space).
.ip b.
If you just installed Ptolemy from tape, and the tape is still
in the tape drive you may skip the next step (c) and go to step (d),
since you will be pointing to the second tar archive on the tape
already.
.ip c.
insert the tape into the tape drive.
.ip
mt -f /dev/nrst8 rewind
.br
(This rewinds the tape -- change the device name if your tape drive
has a different name.)
.ip 
mt -f /dev/nrst8 fsf 1
.ip d.
tar xf /dev/rst8
.ip 4.
If you have used FTP to get the ptolemy gnu file, 
then cd to the directory that contains the "tar.Z" file you
downloaded via FTP.
.ip 5.
You should now have a gnu-xxx.tar.Z file (where xxx is an architecture
supported by ptolemy such as "sun4" or "mips") in your
current directory.
.ip 6.
Note, if they was already a "gnu" directory in "/usr/tools" (see
step (2) above) you will
need to change the commands below.  Replace "/usr/tools"
with the name of the parent directory of the location you have picked
for the ptolemy gnu subset.
.ip
If you are running on a Sun 4 (Sparc, IPC, IPX, etc) then:
.br
zcat gnu-sun4.tar.Z | ( chdir /usr/tools; tar xf - )
.br
If you are running on a DecStation (MIPS) then:
.br
zcat gnu-mips.tar.Z | ( chdir /usr/tools; tar xf - )
.pp
The gnu tar files also contain the gnu source code in
the /usr/tools/gnu/src directory.  
You will save disk space and \*(PT will still run fine if 
you delete all of the gnu source
files. However, if you plan to redistribute the tools 
(give them to anyone else) you must
include sources, according to the Gnu Public License.
Therefore, it may be a good idea to keep these source files around.
.H2 "Testing the Installation
.pp
Note that the following tests assume that you have created a 
user "ptolemy" and installed the system there.  One advantage
of such an installation, is that the user "ptolemy" already has
a working .cshrc and .login file to make startup easier.
.pp
To test \*(PT:
.ip 1.
login as ptolemy
.ip 2.
If the X server is not already running, the .login script will attempt
to start it.  If your installation is different from ours, you may
need to modify .login to work at your site (in particular, you may
need a different
.i path
variable).
.ip 3.
cd demo
.ip 4.
pigi
.ip 5.
Follow instructions in section 2 of the Almagest 
titled, ``Running the Ptolemy Demos'' (section 2.3.1).
.pp
Note that the ptolemy user provides a model of a user properly
configured to run ptolemy.  All the .files in the home directory
are set up according to the tastes of the \*(PT authors,
and according the standard use of windowing software in the \*(PT
development group.
.H2 "Rebuilding Ptolemy From Source"
.pp
If you wish to rebuild \*(PT from source (this step is recommended
if you plan to do major development work, such as adding a
new domain), it is simply a matter of editing the appropriate
configuration file and typing ``make''.  This is explained in
a bit more detail below.
.pp
Configuration files live in the root directory of your
ptolemy system.  If you have installed \*)PT as the 
user "ptolemy" then these file are in the ~ptolemy home directory.
The configuration file are all named ``config-xxx.mk''
where the ``xxx'' is something like "sun4" for a Sun-4 system or
"mips" for a DecStation.  They are included by other makefiles and define
symbols specifying compiler flags, the directory where X include
files are located, etc.  The file that is used is determined by
replacing ``xxx'' above by the value of the ARCH environment variable.
.pp
If you wish to
rebuild using cfront rather than g++, use config-cfront.mk as a starting
point to produce your configuration file.  This has been tested with
cfront 2.1 on a Sun-4; for other platforms, you may need to do some
tweaking.
.pp
To rebuild the system, first adjust the configuration parameters
in the appropriate configuration file.  For example, if you are 
using the Gnu tools on a Sun-4, then you will need to adjust
the "config-sun4.mk" file.
.pp
Next, run make.  We recommend using Gnu make, which is included in the
gnu subset.  (Make sure that the Gnu tools are installed correctly.)
Ultrix make will definitely not work.
.pp
You will get some warnings from the compiler, but the following
warnings can safely be ignored:
.br
any warning about file_id' defined but not used.
.br
 ../../src/kernel/Tokenizer.cc:85: warning: cast discards `const' from pointer target type
.br
 ../../../../src/domains/thor/kernel/fprval.cc:56: warning: ordered comparison between signed and unsigned
.br
 ../../src/ptcl/PTcl.cc:<n>: warning: cast discards `const' from pointer target type (this warning may appear four times with different values of <n>)
.br
 ../../src/ptcl/ptclMain.cc:75: warning: unused variable `ptcl'
.EQ
delim $$
.EN
.\" Local variables:
.\" mode: nroff
.\" End:
