This text is generated from the users_man/installation.ps file.
The TROUBLE_SHOOTING_0.5 file is a subset of this file.
This text file contains the latest and greatest version of the
installation appendix.  The version in the doc.tar.Z file
may be out of date with respect to this version.

Appendix A.  Installation and Troubleshooting
Authors:        Joseph T. Buck
Alan Kamas
Other Contributors:     Christopher Hylands
Edward A. Lee
Kennard White

A.1  Obtaining Ptolemy

Ptolemy is currently available for Sun 4 (Sparc), DecStation 
(MIPS), and HP (Snake) architectures. Installing the system 
requires 90 Megabytes of disk space for Ptolemy (more if you 
optionally remake). Ptolemy also requires at least 8 Megabytes 
of physical memory. The latest information about Ptolemy can be 
found using the command:

finger ptolemy@eecs.berkeley.edu
You may also send any questions on obtaining Ptolemy to the same 
email address: "ptolemy@eecs.berkeley.edu". If you have 
questions about using or enhancing Ptolemy, you should use the 
ptolemy mailing list. See the below for details.


A.1.1  Access via the Internet

Ptolemy is available without support at no charge to 
organizations on the Internet via FTP. Source code, executable, 
and documentation are all available at the FTP site. The 
procedure for obtaining Ptolemy via FTP is as follows:

a.      FTP to Internet host "ptolemy.Berkeley.EDU".
b.      Login as "anonymous"; give your full email address as 
the password.
c.      cd pub
d.      Follow the directions in the "README" file there.

A.1.2  Access via ordinary mail

Organizations without Internet FTP capability can obtain Ptolemy 
without support from:
EECS/ERL Industrial Liaison Program Office
Software Distribution
205 Cory Hall University of California at Berkeley
Berkeley, CA 94720
(510) 643-6687
email: ilpsoftware@eecs.berkeley.edu
There is currently a handling fee of $250 for US orders, $265 
for foreign. These prices are subject to change at any time. 
Please contact the ILP office at the address above for the exact 
price. Printed documentation is included.


A.1.3  Obtaining documentation only

The printed documentation is available separately from the tape. 
Please contact the ILP office at the address above for the 
current price.


A.2  Ptolemy mailing lists

There are two mailing lists for Ptolemy users:
ptolemy-hackers@ohm.eecs.berkeley.edu
ptolemy-interest@ohm.eecs.berkeley.edu
Both mailing lists follow the same administrative procedure. To 
be added or deleted from a mailing list, send a letter with the 
subject ADD ME or DELETE ME to 
MaillingListName-request@ohm.berkeley.edu. For example, to be 
added to mailing list "ptolemy-hackers," send email with the 
subject ADD ME to "ptolemy-hackers-request@ohm.berkeley.edu"

        ptolemy-hackers: A forum for Ptolemy questions and 
issues. Users of the current release who have a Ptolemy 
question, comment, or think they've found a bug should send mail 
to ptolemy-hackers. Ptolemy users in companies and universities 
around the world who are interested in discussing Ptolemy post 
and read from the ptolemy-hackers group.

        ptolemy-interest: A mailing list for Ptolemy 
announcements. Messages about new releases, bug fixes, and other 
information of interest to all Ptolemy users is posted here. 
Note: This is not a discussion group, and you cannot post to 
this mailing list. Message volume is very light. All users of 
Ptolemy should belong to this group in order to stay current 
with work being done on Ptolemy. To be added to the group, send 
mail with the subject ADD ME to: 
"ptolemy-interest-request@ohm.berkeley.edu".


A.3  Installation

Ptolemy is a large software system that relies on a properly 
configured software environment. There are a few things that can 
go wrong in getting Ptolemy running. There is some minimal 
configuration required by each user in order to use the 
graphical interface. The information for doing this is given in 
"Setup" on page 2-1. Here we give the basic information required 
to get from an FTP archive or distribution tape to being able to 
run the system.

Note that this information may change after this manual is 
printed. Thus, the most up-to-date instructions are included in 
ASCII form with the distribution.


A.3.1  Basic Ptolemy installation

First note that the approximate disk space requirements are (for 
the Sun-4 distribution; other distributions are roughly the same 
size):

        Ptolemy: 89 Megabytes
        Ptolemy (after you optionally remake): approximately 120 
Megabytes
        Documentation Postscript Files (optional): 33 Megabytes
        Gnu Binary and Sources (optional): 55 Megabytes
        Additional Sources (needed to port Ptolemy) (optional) 
14 Megabytes.
Important Note: Ptolemy is distributed with source code. The 
source code is contained in a directory called src in the main 
installation directory. Installing this src directory is not 
optional. The src directory contains all of the icons that 
represent stars in all of the domains, plus Tcl code (which is 
interpreted, not compiled, so the source is required at run 
time). If you absolutely must discard the source code, you can 
remove all files under src with extensions .cc, .h, or .c.

The preferred way to install Ptolemy requires that you create a 
fictitious 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.

If you are loading Ptolemy from a tape, do the following:
a.      cd /tmp
or any directory where you have write permission and there is at 
least 71 Megabytes of free disk space. (If you do not have this 
amount free, you can extract the four files one at a time. See 
the tar man page for details. You will still need at least 30 
Megabytes of free space.)

b.      Load the tape into your drive
c.      mt -f /dev/nrst8 rewind
This rewinds the tape - change the device name if your tape 
drive has a different name.
d.      tar xf /dev/nrst8
If you have used FTP to down load the files, then cd to the 
directory that contains the files you downloaded via FTP.
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:

a.      zcat pt-0.5.doc.tar.Z | ( chdir ~ptolemy/..; tar xf - )
This uncompresses the documentation, changes directory to the 
parent of the "ptolemy" user, and then creates all of the 
documentation files.

b.      zcat pt-0.5.src.tar.Z | ( chdir ~ptolemy/..; tar xf - )
This uncompresses the src and creates the source files. You must 
not skip this step. Ptolemy 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.


c.      If you are running the DecStation (MIPS) version of 
Ptolemy:
zcat pt-0.5.mips.tar.Z | ( chdir ~ptolemy/..; tar xf - )
If you are running the Sun 4 (Sparc, IPC, IPX, etc.) version:
zcat pt-0.5.sun4.tar.Z | ( chdir ~ptolemy/..; tar xf - )
If you are running the HP Precision Architecture (HP PA) version:
zcat pt-0.5.hppa.tar.Z | ( chdir ~ptolemy/..; tar xf - )
This uncompresses the binaries and creates the executable files. 
Note that is possible to install binaries for multiple platforms 
on the same file system because different directories are used 
for each set of binaries. Just execute whichever of the above 
commands apply.

Note that the sun4 Ptolemy binaries in pt-0.5-sun4.tar.Z were 
built with the C and C++ optimizer turned on(-O), whereas the 
mips and hppa binaries were built with no optimization. Note 
further that the hppa port in Ptolemy 0.5 is fundamentally 
unchanged from the hppa port in Ptolemy 0.5beta. We anticipate 
rereleasing the hppa port sometime in the near future. See the 
Known Bugs section below for more information.

d.      If you are planning on porting Ptolemy, you will need 
the other sources file:
zcat pt-0.5.other.src.tar.Z |( chdir ~ptolemy/..; tar xf - )
The other.src tar file includes sources to a subset of octtools 
(including vem), tcl/tk and xv.
e.      You no longer need the *.tar.Z files that your got from 
the FTP site or the tape. Remember to delete these files to free 
up disk space.

f.      The X11 program xv is used by some of the image 
processing demos. If you already have a version of xv, or you 
don't plan on doing any image processing, you can also remove 
the xv binary in $PTOLEMY/bin.$ARCH/xv.


A.3.2  Installation without creating a "ptolemy" user

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 well. In 
troubleshooting an installation, having the "ptolemy" user 
properly configured can be very valuable.

However, we recognize the some sites resist the creation of 
fictitious users. Consequently, Ptolemy can be installed 
anywhere. If you do this, every 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".


A.3.3  Special considerations for use under Open Windows

Ptolemy was developed using the X11R4 or X11R5 distributions 
from MIT. Although Ptolemy runs fine under Open Windows 2, there 
are problems with running the Ptolemy graphical interface with 
Open Windows version 3.0. 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.

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 
you have installed Open Windows in a non-standard place, into 
$OPENWINHOME/lib). 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 
LD_LIBRARY_PATH.

After installation, the ptolemy account will contain several 
scripts for starting up X11R5 (Xrun), Open Windows with olwm 
(Xrun.ow), or Open Windows with twm (Xrun.ow.twm).

Some users have reported problems with running xedit under Open 
Windows after setting their LD_LIBRARY_PATH. One workaround is 
to set the PT_DISPLAY environment variable to use an editor 
other than xedit, such as vi.

If only have Open Windows, and not X11R5 and you plan on 
rebuilding from source, you may need the libraries in 
athena.sun4. athena.sun4 is part of the pt-0.5.sun4.tar.Z tar 
file.


A.3.4  GNU Installation

For convenience, some software from the Free Software Foundation 
is included on the distribution tape. This includes the compiler 
used to make this distribution of Ptolemy, which is also the 
compiler you should use to extend Ptolemy. In particular, 
Ptolemy supports dynamic linking of newly defined stars. Dynamic 
linking will not work, however, if the new stars are compiled 
with a different version of the compiler than that used for the 
rest of the system. Thus, you must either use the same compiler 
that we used for this distribution of Ptolemy, or you must 
recompile the entire Ptolemy system. Note that this is not a 
complete set of Gnu software.

It is also possible to build Ptolemy with Sun's port of AT&T's 
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 cfront code. 
When you completely rebuild Ptolemy, you must be sure to first 
remove all previously compiled object files.

The Gnu compiler is dependent upon where it was built. The 
executable that we supply assumes that Ptolemy is installed in a 
directory called /users/ptolemy. If you do not wish to rebuild 
the compiler, then you must either install Ptolemy in this 
directory, or create a symbolic link from this directory to the 
actual directory in which Ptolemy is installed. If you cannot 
install such a link, then you will still be able to run Ptolemy, 
but you may not be able to dynamically link new stars nor 
recompile Ptolemy.

You may still be able to use this compiler by setting the 
following Gnu environment variables before using the compiler. 
We provide a script in $PTOLEMY/bin/g++-setup that sets these 
variables. If you will always be using the prebuilt Gnu compiler 
shipped with Ptolemy, you may want to edit your copies of 
$PTOLEMY/bin/pigiEnv.csh and $PTOLEMY/bin/ptcl and add the 
following line:

source $PTOLEMY/bin/g++-setup
You should not set these variables if you are using a version of 
the GNU compiler that is different from the version that we are 
shipping (If you are using a different version of the Gnu 
compiler, then you will probably need to do a complete rebuild 
for dynamic linking to work). For reasons we have not been able 
to track down, setting the environment variables does not work 
in all installations. Creating a link is better. Here are the 
variables:

setenv GCC_EXEC_PREFIX $PTOLEMY/gnu/$ARCH/lib/gcc-lib/$ARCH/2.5.8/
setenv C_INCLUDE_PATH $PTOLEMY/gnu/$ARCH/lib/gcc-lib/$ARCH
setenv CPLUS_INCLUDE_PATH $PTOLEMY/gnu/$ARCH/lib/g++-include:$PTOLEMY/gnu/$ARCH/$ARCH/include
setenv LIBRARY_PATH $PTOLEMY/gnu/$ARCH/lib
The above assumes that the environment variable PTOLEMY is set 
to the name of the installation directory for Ptolemy, and ARCH 
is set to the type of workstation (one of sun4, mips, or hppa).

To install the Ptolemy Gnu subset, proceed as follows:
a.      If you have Ptolemy on tape, then cd to the directory 
you used to download the files from the tape in the "Basic 
Ptolemy installation" steps above. If you have used FTP to get 
the Ptolemy Gnu file, then cd to the directory that contains the 
files you downloaded via FTP.

You should now have a pt-0.5.gnu.xxx.tar.Z file (where "xxx" is 
an architecture supported by Ptolemy such as "sun4", "hppa", or 
"mips") in your current directory.

b.      If you are running on a Sun 4 (Sparc, IPC, IPX, etc.) 
then:
zcat pt-0.5.gnu.sun4.tar.Z | ( chdir ~ptolemy/..; tar xf - )
If you are running on a DecStation (MIPS) then:
zcat pt-0.5.gnu.mips1.tar.Z |( chdir ~ptolemy/..; tar xf - )
zcat pt-0.5.gnu.mips2.tar.Z | \
            chdir ~ptolemy/gnu/mips/lib/gcc-lib; tar xf - )
If you are running on an HP workstation (HPPA) then:
zcat pt-0.5.gnu.hppa.tar.Z | ( chdir ~ptolemy/..; tar xf - )
c.      There is also a gnu tar file which contains the Gnu 
source code. You will save disk space and Ptolemy will still run 
fine if you do not untar the Gnu source code. 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.

If you want to untar the Gnu source code:
zcat pt-0.5.gnu.tar.Z | ( chdir ~ptolemy/..; tar xf - )
d.      You no longer need the *gnu*.tar.Z files that your got 
from the FTP site or the tape. Remember to delete these files to 
free up disk space.


A.3.5  Testing the Installation

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 start-up easier.

To test Ptolemy, assuming you have set up a "ptolemy" user:
a.      login as ptolemy
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 path variable).

b.      cd demo
c.      pigi
Follow instructions in "Starting Ptolemy" on page 2-2.
If you have not set up a "ptolemy" user, then set your PTOLEMY 
environment variable to point to the installation directory, and 
then

cd $PTOLEMY/demo
pigi
Note that the ptolemy user provides a model of a user properly 
configured to run Ptolemy. All the dot files (.cshrc, .login 
etc. ) in the home directory are set up according to the tastes 
of the Ptolemy authors, and according the standard use of 
windowing software in the Ptolemy development group.


A.3.6  Rebuilding Ptolemy From Source

If you wish to rebuild Ptolemy 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.

To do a build of all of Ptolemy using the Gnu compiler from the 
distribution, first make sure that either Ptolemy is installed 
in /users/ptolemy, or there is a symbolic link from 
/users/ptolemy to the installation directory. Alternatively, you 
can try setting the four environment variables as described 
above. Next make sure that $PTOLEMY/bin.$ARCH is in your path 
(this is where the compiler is installed). Then proceed as 
follows:

a.      cd $PTOLEMY (or cd /users/ptolemy)
b.      make install
An easier approach is to log in as "ptolemy" (assuming you 
created such a user). The path and environment variables are 
already set up for this user. Yet a third approach is to make 
use of the setup for this user, as follows:

a.      cd $PTOLEMY (or cd /users/ptolemy)
b.      edit $PTOLEMY/.cshrc to define PTOLEMY correctly
c.      source $PTOLEMY/.cshrc
d.      make install
If you wish to customized your installation, you may have to 
edit the configuration files. These files are in $PTOLEMY/mk. 
The configuration files are all named config-$ARCH.mk where the 
"$ARCH" 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.

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.

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.

Next, run make. We highly 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. Sun 
make will fail on certain makefiles that have Gnu make 
extensions.

You will get some warnings from the compiler, but the following 
warnings can safely be ignored:
        any warning about file_id defined but not used.
        many warnings about cast discards const.
        ../../../../src/domains/thor/kernel/fprval.cc:56:
warning: ordered comparison between signed and unsigned
This warning may appear four times with different values of <n>.
        ../../src/ptcl/ptclMain.cc:75: warning: unused variable 
`ptcl'
On the mips platform, you may see messages about
        warning, WORDS_PER_FIX not found in original or external 
symbol tables, value defaults to 0
These messages are a result of the mips -G 0 option, see the DEC 
cc and ld manpages for more information.

A.3.7  Other useful software packages

Some parts of Ptolemy use other software packages. The packages 
below are all available on the net. If you have net access, you 
can find lots of FAQs (Frequently Asked Questions) via anonymous 
ftp at pit-manager.mit.edu in /pub/usenet/news.answers.

        The Utah RLE Toolkit (URT) is used by some of the 
Multimedia demos. URT is available via anonymous FTP from 
cs.utah.edu in /pub/urt-*

        The following GNU utilities are available via anonymous 
ftp from prep.ai.mit.edu via anonymous FTP. See the file 
/pub/gnu/GETTING.GNU.SOFTWARE on that site. For further 
information, write to:

Free Software Foundation
675 Mass Ave
Cambridge, MA 02139
USA
The following GNU software is used by Ptolemy:
        ghostscript - PostScript previewer
        gdb - needed for pigi -debug
        groff - Can be used to format manual pages instead of 
ditroff

A.4  Troubleshooting

This section lists common difficulties encountered when Ptolemy 
is installed or run. This list is, of course, by no means 
complete. If you do not find your particular problem here, refer 
to "Additional Resources" section below.


A.4.1  pigi fails to start when put in the background

A common problem occurs when pigi is started in the background 
and the user has the line
stty tostop
in their .login or .cshrc file. This command configures the 
terminal to halt any process that is running in the background 
when it tries to write to the terminal. One possible fix is to 
run pigi in the foreground. Another possible fix is to eliminate 
this command from your .login file.


A.4.2  pigi fails to start with a message about not finding fonts

The default fonts for vem are specified in the file 
$PTOLEMY/lib/pigiXRes9, and also pigiXRes9.bw and pigiXRes9.cp. 
These files define a set of X window resources. The pigiXRes9.bw 
file is used if pigi is started with the -bw option. The 
.pigiXRes9.cp file is used in pigi is started with the -cp 
option. The definitions in these files can be overridden by the 
user. For example, a user who prefers to use microscopic fonts 
could set the X resource as follows:

Vem*font:               *-times-medium-r-normal--*-120-*
If, however, the fonts defined in these files on not available 
on the system, then the Ptolemy installer should change them in 
the files $PTOLEMY/lib/pigiXRes9*.

The fonts for tk (and hence, the fonts for most of the dialog 
boxes) are specified in $PTOLEMY/lib/tcl/ptkOptions.tcl. These 
may similarly require changing at some sites. In the worst case, 
if many standard fonts are not available, it may be necessary to 
redefine the default fonts built into the tk source code, and 
recompile tk.


A.4.3  pxgraph fails to come up or displays a blank window

If the pxgraph program is given exceptional numbers, such as the 
IEEE floating-point Inf, -Inf, or NaN ("not a number"), then it 
will issue a cryptic error message "problems with input data" 
and will fail to display a plot. The stars that use pxgraph are 
supposed to intercept this and pop up an error message in a 
window. However, on some platforms, as of this writing, this 
does not work. On such platforms, the error message, 
unfortunately, goes to the standard output, which may be buried 
several layers deep in your windowing system. It is also 
possible for the standard output to be lost, so that no error 
message appears. Thus, if you get such a pxgraph failure, look 
for instabilities in your Ptolemy schematic that would cause it 
to produce such exceptional numbers.


A.4.4  Old flowgraphs do not work (facets are inconsistent)

A pigi schematic contains references to icons. These icons are 
referenced by their location in the file system, typically using 
either an absolute path, a path relative to user's home 
directory, or a path relative to the environment variable 
PTOLEMY. If the master for any of these icons is not in the 
expected place, vem will issue a warning, telling you that the 
facet is inconsistent. In place of the icon in the schematic 
there will be blank space. To find out what icon masters are 
missing, run the program masters. Instructions for doing this 
are given in "Copying and moving designs" on page 2-43. Invalid 
masters will be labeled "INVALID". You must replace the invalid 
reference with a reference to a valid master.

One typical scenario for users upgrading from version 0.4.1 of 
Ptolemy to version 0.5 is that they will have references to 
masters in the directory tree ~ptolemy. But Ptolemy 0.5 may be 
installed somewhere else. One solution is to use the masters 
program to replace "~ptolemy" with "$PTOLEMY".

If you have flowgraphs dating back to the 0.3.1 version, you 
will encounter some significant incompatibilities. In 
particular, several stars that were included in the 0.3.1 
release of Ptolemy have been renamed. The objective was to adopt 
a consistent naming policy across all domains. One major benefit 
of this is the ability to migrate universes and galaxies from 
one domain to another. A consequence, however, is that some of 
your universes and galaxies will have inconsistencies (they will 
point to icons that no longer exist in the current release). 
Please see the file "$PTOLEMY/lib/rename/README." This file 
explains how to upgrade your universes and galaxies to the 
current release.


A.4.5  Error: ld.so: libXext.so.4: not found

You have not installed the shared library needed by Ptolemy when 
it is used under Open Windows. See the "Open Windows" section in 
the installation guide.


A.4.6  Problems starting up clients such as xedit under Open 
Windows

Use the PT_DISPLAY variable to use a different editor. See the 
"Environment Variables" section in the Interactive Graphical 
Interface chapter of the User's Manual.


A.4.7  Problems with the colormap

Some applications, for example FrameMaker 4.0, allocate as many 
colors as they can from the colormap when they start up. This 
may force applications that are started later (such as pigi) to 
use a very restricted set of colors. When you start pigi, if the 
welcome window appears in black and white, then you may have 
such a situation. If the situation is worse, and there are not 
enough colors in the colormap for vem to start, then you may not 
even get this far. One solution is simply to exit the offending 
application (e.g. FrameMaker), and start pigi over. A better 
solution is to configure the offending application to use fewer 
slots in the colormap. We have found that for FrameMaker 4.0, 
the following X resources (placed in your .Xdefaults file) 
usually solve the problem:

Maker.targetExactColors: 2
Maker.minimumExactColors: 0
Maker.targetColorCube: 4
Maker.minimumColorCube: 1
This still leaves FrameMaker with a very rich set of colors to 
use. You may need to replace the 2 or 4 with smaller numbers if 
you have other color-intensive applications running (such as 
root window pictures of beaches in Tahiti).


A.4.8  Ptolemy simulation runs do not stop

In the SDF domain, particularly, it is possible to have 
multirate systems where a single iteration is very large number 
of firings of stars. This happens when the number of samples 
produced or consumed by various connected stars in the system 
are mutually prime, or they have very large least common 
multiples. If a simulation is taking an unreasonable amount of 
time, then look for such mutually prime numbers. Sometimes, in 
such circumstances, it can take a long time for the simulation 
to respond to pushing the "stop" button. It should, however, 
eventually respond.


A.4.9  Generated code in CGC fails to compile

The targets in CGC are configured by default with reasonable 
guesses about the compile and link options that are required to 
compile the code. However, the actual options required depend on 
your system configuration. For instance, your default cc 
compiler may not have been configured to automatically find the 
X11 include files. You might, therefore, get an error message 
the Xlib.h cannot be found. You should find out where on your 
system Xlib.h is installed, and add a compile option of the form 
"-Lpath_name" where path_name is the full path of the directory 
containing the file. Alternatively, you can create a symbolic 
link from /usr/include to the directory (you must have root 
permission to do this).

Certain compiles will change their behavior depending on the 
values of certain environment variables:
        The hppa cc compiler will use the CCOPTS environment 
variable. If your X11 libraries were at /usr/sww/X11R5/lib, then 
one could exit pigi, set the variable

setenv CCOPTS -L/usr/sww/X11R5/lib
and restart pigi. Then when you compile CGC demos with hppa cc, 
you should be able to find the proper libraries. See the hppa cc 
man page for more information.

        GNU gcc will also use certain environment variables. The 
LIBRARY_PATH variable may help:
setenv LIBRARY_PATH /usr/sww/X11R5/lib
See the gcc documentation for more information.

A.4.10  Ptolemy won't recompile

You may be using a substantially different version of the Gnu 
compiler. The system is most likely to build if you use the same 
tools that we used originally. The Gnu tools we used are 
supplied with the Ptolemy distribution.


A.4.11  Missing symbols while linking pigiRpc

On the sun4 with libg++-2.5.2, if you compile pigiRpc with the 
g++ -O option, then you may have missing symbols while linking 
pigiRpc. The workaround is to upgrade to libg++-2.5.3. We 
shipped libg++-2.5.2 with the 0.5beta, but we are shipping 
libg++-2.5.3 with the final 0.5 release.


A.4.12  Error involving xedit

The program xedit is a program provided with Ptolemy to display 
files on your screen during a Ptolemy run. If there is some 
problem with xedit that you cannot solve, or you do not like 
xedit, it is possible to change the display program used by 
Ptolemy. To do this, you need to set the PT_DISPLAY environment 
variable before you run pigi. For example, to use PT_DISPLAY to 
view files in a new xterm window with the vi editor, do

setenv PT_DISPLAY "xterm -e vi %s"
The value of the PT_DISPLAY variable is a printf format string 
with one %s in it. That %s is replaced with the file to be 
viewed, for look-inside commands and to view generated code. The 
default value is "xedit %s".


A.4.13  Emacs confuses .pl files with Prolog

The .pl extension used to define Ptolemy stars is the same 
extension used for the Prolog language. Some text editors, such 
as emacs, have special modes for editing Prolog files. These 
modes are inappropriate for editing Ptolemy files. You can 
create the following line your .emacs file in your home 
directory:

(setq auto-mode-alist (cons '("\\.pl$" . c++-mode) 
auto-mode-alist))

A.4.14  The window manager crashes

The window manager twm sometimes crashes when you are running 
Ptolemy. We do not know why. Our solution is to simply restart 
it. You may wish to make sure your configuration does not log 
you out when the window manager exits.


A.4.15  Path and/or Environment Variables not set in "debug" pigi

When running Ptolemy's interactive graphical interface with the 
debug option:
pigi -debug
The path is not set correctly, or environment variables are not 
at their normal values. This is caused by the Gnu debugger, GDB, 
overwriting values set by the pigi start-up script. From the GDB 
manual:

*Warning:* GDB runs your program using the shell indicated by 
your `SHELL' environment variable if it exists (or `/bin/sh' if 
not). If your `SHELL' variable names a shell that runs an 
initialization file--such as `.cshrc' for C-shell, or `.bashrc' 
for BASH--any variables you set in that file affect your 
program. You may wish to move setting of environment variables 
to files that are only run when you sign on, such as `.login' or 
`.profile'.

If your .cshrc file specifies a value for a variable, it will 
override anything in the pigi start-up script. If this is the 
case, perhaps setting SHELL to /bin/sh before firing off the 
debugger will fix the problem.


A.4.16  CGC demos won't run

If . (dot, the current working directory) is not in your path, 
then when you run the CGC demos you may see:
sh: butterfly: not found
The workaround is to exit pigi, place . in your path, and 
restart pigi. For security reasons, placing . in your path after 
all of your other directories is best:

set path = ($path .)

A.4.17  EOF messages while using tar on Suns

There is a bug in the SunOS4.1.3 version of /bin/tar. Sometimes 
a command such as:
zcat atarfile.tar.Z | /bin/tar -xf -
may produce error message such as:
tar: read error: unexpected EOF
when reading from a pipe. One workaround is to use GNU tar, 
another is to uncompress the tar file, and then use /bin/tar on 
the uncompressed file:

uncompress atarfile.tar.Z; /bin/tar -xf atarfile.tar

A.4.18  Dynamic Linking fails

Ptolemy has the ability to load stars dynamically during run 
time. The stars are compiled into .o files and loaded with the 
Unix loader. Dynamic linking is tricky and dependent on the Unix 
loader. There are several reasons dynamic linking can fail:

        Dynamic linking is not currently supported on the hppa 
and hppa.cfront platforms. We are working towards fixing this in 
a later release.

        If you are upgrading from an earlier release, including 
Ptolemy-0.5beta, be sure to remove all the .o files in the 
directory where the source files for you star is.

        If you are using prebuilt Ptolemy binaries, be sure that 
you are using the prebuilt Gnu compiler that is also available 
with the Ptolemy binaries. The alternative is to rebuild Ptolemy 
with your local Gnu compiler, but be aware that versions earlier 
than gcc-2.5.6 and libg++-2.5.3 have bugs. gcc-2.4.x and 
libg++-2.4.x and earlier are know to have serious bugs, so you 
may want to upgrade. For more information, see the Gnu 
Installation section in this Installation document.

        If you are using prebuilt Ptolemy binaries and have the 
prebuilt Gnu compiler, be sure that either the Ptolemy 
distribution is available as /users/ptolemy, or you are setting 
the Gnu environment variables in $PTOLEMY/bin/g++-setup. Again, 
see the Gnu Installation section.

        If, at linktime, you see messages about undefined 
symbols, and the undefined symbols begin with _vt, then you 
probably have compiler version incompatibilities. Note that you 
can find out what files have the undefined symbols by using the 
Unix nm command.

        Dynamic linking may not work on machines that have a 
different release of the OS. In particular, we found that 
dynamic linking with the prebuilt binaries failed on mips 
running Ultrix4.3 if our mips prebuilt binaries were created 
under Ultrix4.3A. The workaround is to relink Ptolemy on the 
local machine.

        If you are having problems compiling the star from 
Ptolemy, try running the compile by hand from the shell. 
Unfortunately, part of the compile command is not always visible 
in the vem window. To see the all of the compile command, try 
running a few vem commands, such as `i' (look-inside) to flush 
the vem buffer. Once you have produced a .o file, you can load 
the .o file into Ptolemy with the load-star command.


A.4.19  The DE stars "And" and "Or" no longer work

These stars have been replaced by the Logic star. Use this new 
star instead.

A.4.20  Multi-porthole Galaxies Fail

If a galaxy contains a multi-porthole input or output, and the 
icon of the galaxy is named Foo.input=2, Foo.output=2, etc., the 
galaxy will fail to compile. This is because Ptolemy behaves as 
if anything ending in input=X or output=X must be a star. Avoid 
using names like "Foo.input=3" for galaxies.


A.5  Known Bugs

There are a number of known bugs that we have not had a chance 
to fix.

A.5.1  Bugs in Vem

        When graphical animation is turned on and a simulation 
is running, if you execute the "look-inside" command, vem 
terminates the pigiRpc application.

        Labels that end with a carriage return are neither 
displayed nor printed correctly.
        Editing icons stimulates a memory leak in vem that can 
make the process grow quite big. After editing a few dozen 
icons, you may wish to exit vem and restart.

        When you edit a label, a dialog box frequently appears 
with the message "ambiguous layer" and a checklist of colors. 
Check and color and continue. The choice of color has no effect.

        The "layer" command only works when editing icons, not 
when editing schematics.
        The "copy-objects" command will copy from one window to 
another only when editing icons, not when editing schematics.

        If you obtain the other.src tar files and attempt to 
build vem from scratch, do not use gcc, use cc instead. Vem 
binaries built with gcc may fail to start up, or may crash later 
with memory errors.


A.5.2  Bugs in pigi

        The "run-all-demos" command does not always work. In 
particular, it fails on most Tcl/Tk demos, because these assume 
that a run control panel is present, but the run-all-demos 
command does not open a control panel. Also, some demos 
deliberately trigger an error, in order to demonstrate some 
failure modes in the domain. The run-all-demos command quits 
when it encounters such an error.

        It is possible to make more than one icon to represent a 
given star. For instance, the icon And and And.input=2 refer to 
the same star, but the former can have any number of inputs, 
while the latter has exactly two inputs. As of this writing, 
this facility does not work for galaxies. You should create only 
one icon for each galaxy.

        Simulations that run for a very long time may not 
respond quickly enough to pushing the stop button in the control 
panel.

        If you try to run the CGC demos that generate sound, and 
you do not have a properly configured audio device, or you do 
not have write permission to /dev/audio, then you get a cryptic 
and uninformative error message, rather than something useful.

        The CGC Multi-processor demos have Berkeley machine 
names hardwired into them. These demos probably won't work at 
other sites unless the machine names are changed.

        The CGC tcltk BallAsync demo fails on the mips platform. 
We believe that this is due to interactions between tcltk and 
the select() function. This bug only affects demos which use the 
sleep star on the mips platforms.

        The sim-CG96 target was not compiled into the release. 
Thus, the only CG96 target available is the default-CG96 target. 
Unfortunately, the demos use the sim-CG96 specific IO stars, so 
they cannot be run with the default target. To use the sim-CG96 
target, add the line below to the file $PTOLEMY/mk/stars.mk and 
rebuild pigi.

CG96TARGETS =   $(CG96T)/Sim96Target.o

A.5.3  Bugs in pxgraph

        If pxgraph is given only one point to plot, nothing 
appears in the plot window.
        If pxgraph is given exceptional numeric input, such as 
the IEEE floating point Inf,
-Inf, or NaN, then it displays a blank window only.
        If pxgraph is given an empty file to plot, all it does 
is send a message "problems with input data" to the standard 
output.


A.5.4  HPPA specific bugs

As stated earlier, the hppa port in Ptolemy0.5 is fundamentally 
unchanged from the hppa port in Ptolemy0.5beta. We anticipate 
rereleasing the hppa port soon. Below is a list of known hppa 
specific bugs.

        Dynamic linking does not work on the hppa.
        The hppa.cfront architecture is new port, and is known 
to have problems with random numbers. The hppa does not have a 
random() function, and the rand() function returns numbers over 
a different range than random(). There is a patch for this bug 
available via anonymous ftp from ptolemy.eecs.berkeley.edu at 
pub/ptolemy/ptolemy0.5/patches/pt-0.5-patch1.

        On the hppa, pxgraph does not print hardcopy perhaps 
because the hppa does not have an lpr command.
        On the hppa, compiling with gcc-2.5.8 with the -O option 
fails because of an undefined symbol. This is a Gnu compiler bug.

        On the hppa, oct2ps core dumps, so printing facets 
probably won't work.
        On the hppa, the octtools masters program may core dump.
        On the hppa, problems have been reported in the de 
domain. The de:basic:real-time demo hangs.
        On the hppa, under cfront, Xhistogram may have rounding 
problems.

A.5.5  GNU compiler bugs

If you write your own stars, then be aware that gcc-2.5.8 may 
not choose the expected cast. In particular, g++ has been know 
to cast everything to Fix if the explicit cast is omitted. The 
arithmetic is then performed using fixed-point computations. 
This will be dramatically slower than double or integer 
arithmetic, and may yield unexpected results. It is best to 
explicitly cast states to the desired form. For more 
information, see the ptlang chapter in the Ptolemy Programmers 
Manual.

On the mips, files must be compiled with the -G O option for 
dynamic linking to work. Unfortunately, under gcc-2.5.8, gcc 
spits out lots of warnings like:

warning: T_EOF not found in original or external symbol tables
These warnings may be ignored.

A.6  Additional Resources

The best, most complete source for information on Ptolemy is to 
be found in the Ptolemy manual, The Almagest. The manual is 
included in every distribution. In addition, the printed 
documentation is also available from the ILP office at the 
following address:

        EECS/ERL Industrial Liaison Program Office
Software Distribution
205 Cory Hall
University of California at Berkeley
Berkeley, CA 94720
(510) 643-6687
email: ilpsoftware@eecs.berkeley.edu
A second source is the "ptolemy-hackers@ohm.eecs.berkeley.edu" 
mailing list. This list provides a forum for Ptolemy questions 
and issues. Users of the current release who have a Ptolemy 
question, comment, or think they've found a bug should send mail 
to ptolemy-hackers. See the "Mailing Lists" section above for 
details.

Another source is the Ptolemy FTP site. To access this, use 
anonymous FTP to ptolemy.eecs.berkeley.edu. The directory 
"pub/ptolemy/papers" contains some of the latest Ptolemy papers 
and articles. The directory "pub/ptolemy/mailing-lists" contains 
the logs from the "ptolemy-hackers" mailing list. Check there to 
see if your question has been asked before.

