.\" @(#)setup	2.11	12/1/92
.H1 "Setup"
.pp
This section explains how to configure a user to run pigi.
If someone has done this for you already, you may skip this section.
It includes enough information about the window system
for the novice user to get started.
.pp
Usually, when \*(PT is installed on your system, a
fictitious user named `ptolemy' is created.
This user is configured according to the tastes
of the authors of Ptolemy.
To configure your own account to behave the same way,
you can copy all the dot files (hidden files whose names
begin with a period) from the directory ~ptolemy
into your home directory.
You can see these files with the ``ls -a ~ptolemy'' Unix command.
Unless you are a new user, however, you will probably not want to overwrite
features already defined in your own dot files.
In this case, you will need to extract the features you desire
from the dot files in ~ptolemy and add them to your own.
To make this easy to do, we explain below the salient features
of each of these files.
.H2 "Hosts"
.pp
Pigi runs as two separate processes, one of which is started using
.i rsh 
(remote shell).  In order for the second process to start properly, you
may need to have a file in your home directory called ``.rhosts''
with the line
.(c
machine_name user_name
.)c
where these names depend on who you are and what your machine is
called.  If rsh is not granted permission, you will receive an
uninformative message saying ``Permission denied.''  If you see this,
it means you must fix your .rhosts file.
.Ir "permission denied"
.pp
As an alternative, the system manager may have set up the file
``/etc/hosts.equiv'' to make all the workstations on your cluster
``equivalent''.  If so, you need not bother with .rhosts.
.H2 "Environment Variables"
.pp
The most basic requirement
is that \*(PT executables be in your path.
.IE path
.b Important:
If you are a csh user,
this should be done in your .cshrc file, rather than your .login file,
because RPC applications are started as separate processes,
and new processes do not examine the .login file.
.pp
The ~ptolemy/.cshrc file defines the path variable to include the appropriate
bin directories to run \*(PT.
.IE "cshrc file"
The pertinent lines read:
.EQ
delim off
.EN
.(c
if (! $?ARCH) setenv ARCH `/bin/arch`
set path = ( . ~ptolemy/bin ~ptolemy/bin.$ARCH ~ptolemy/octtools/bin ... )
.)c
.br
The first of these lines sets your environment variable
.c ARCH
to the name of the type of machine you are running (e.g. sun3,
sun4, vax, or mips).
The second puts the \*(PT and Oct bin directories into your path.
If you add these lines to a previously existing .cshrc file,
be sure to put  these lines at the end of the file, after
any other directives that set the path variable.
.pp
If you plan to print out any \*(PT documents, you will need to set
the PRINTER environment variable.  In ~ptolemy/.cshrc the pertinent
line reads:
.(c
setenv PRINTER lw
.)c
You should replace
.c "lw"
with whatever printer name you are using.
.pp
If, for some reason, you wish to use an alternate version of the
.i pigiRpc
process, you will need to set your PIGIRPC environment variable
to the complete pathname of the executable file for the ``alternate
pigiRpc'' you wish to use (advanced users use this feature when
they want to, say, link in their own domains to Ptolemy).
.Ir "customized pigiRpc"
.H2 "If There Is No `ptolemy' User"
.pp
If \*(PT has been installed without creating a `ptolemy' user,
then you must set the environment variable PTOLEMY to point
to the main directory of the \*(PT installation.
If \*(PT is installed in /usr/tools/ptolemy, for example,
your .cshrc file should read:
.(c
setenv PTOLEMY /usr/tools/ptolemy
.)c
Whenever the documentation refers to `~ptolemy', you should use
`$PTOLEMY'.
.H2 "Running Pigi using Open Windows"
.pp
Sun does not provide the Athena widgets in the Open Windows
distribution; these are required by the VEM editor (the Athena widgets
are a freely distributable toolkit for X11 developed at MIT).  For
this reason, we have provided a copy of the library on the tape, in
the directory ``~ptolemy/athena.sun4''.  The simplest way to install
them is to simply copy the files in this directory to the directory
containing the Open Windows libraries, which is usually
``/usr/openwin/lib'' or ``$OPENWINHOME/lib''.
.pp
Pigi will run under Sun's Open Windows Version 2 or 3, once the Athena widgets
are installed.  This document will
not attempt to teach you how to use Open Windows; there are excellent
tutorial documents available from Sun.  We'll assume as a starting
point that you are configured to run Open Windows;
.i "do not"
attempt to use the .login and .cshrc in the ptolemy account in
this case.  First, make sure that your .cshrc file defines the ARCH
environment variable as above.  Now add the
directories ``~ptolemy/bin'' and ``~ptolemy/bin.$ARCH'' to your
path, as described above.  You'll need to have the ``olwm'' window
manager run in the mode where focus follows the mouse (in this
mode, your keystrokes go to whatever window your mouse points to);
to do this, find the line in your .xinitrc file that invokes olwm;
add the option
.c -follow
to the olwm command.  If, for some reason, you must run olwm in the
click-to-focus mode, you must click the mouse in each window before
pigi will accept keyboard commands in that window; it is possible
but annoying to use pigi this way.  An alternative is to add the
following line to your ``.Xdefaults'' file:
.(c
OpenWindows.SetInput:	followmouse
.)c
.pp
There is a fatal interaction between VEM and the Open Look Window Manager
(olwm) in Version 3 of Open Windows.  One workaround is to use the
.i twm
window manager from the X11R4 distribution instead; it is included
on the distribution tape, along with its manual entry, which can be
found in ``~ptolemy/doc/man/man1/twm.1''.  This problem was discovered
too late to know whether the problem is in Open Windows or in VEM;
we apologize for making you use an uglier window manager.
