Installing Ptplot

Ptplot 5.6-alpha requires Java 1.3 or later. Java 1.4.2 is preferred, we use Java 1.4.2_08. Java 1.4 has a bug concerning viewing local applets that have spaces in the path name, for details, see the Troubleshooting Guide.
To run Ptplot, the Java runtime environment (JRE) is sufficient.
To run the applets in a browser, the Java plug-in is required.
To extend Ptplot with your own Java code, the Java development kit (JDK) or an equivalent Java development environment is required. The JDK includes a Java compiler.

To run Ptplot 5.6-alpha applets, you must install the version 1.3 or later of the Javasoft Java Plug-in. In theory, it should be possible to run Ptplot using the Java 1.2 plug-in, but we recommend upgrading to the Java 1.4.2 plug-in.

If you will be extending the Ptplot classes, then you should install the Java 1.4.2 Java Development Kit: http://java.sun.com/j2se/1.4/

If you do not want to require your users to install the Java 1.4.2 plug-in, then you should stick with Ptplot 3.1, which does not use Swing.

Ptplot is distributed in several formats.

Instructions for the tar file and zip file format.

Instructions for the InstallAnywhere installer.

As part of the Ptolemy II distribution - This page covers the above two cases, for information about installing Ptolemy II see $PTII/doc/index.htm

Ptplot Installation under Unix or Windows with Cygwin from tar or zip files

Ptplot is shipped with the java files precompiled, so you need not recompile. However, if you are using the standalone scripts such as ptplot, then you may want to go through the installation procedure so that the standalone scripts are properly localized.

This tar file (ptplot5.6-alpha.tar.gz), will unpack into called ptplot5.6-alpha, and the configure-make-make install process will not install any files outside of this ptplot5.6-alpha directory. So if you unpack the tar file into /usr/local, after installing you will have /usr/local/ptplot5.6-alpha, and you may want to tell users to add /usr/local/ptplot5.6-alpha/bin to their PATH. The scripts in the bin directory will run the plotter as a standalone application, or they can add /usr/local/ptplot5.6-alpha to their Java CLASSPATH.

If you are using Windows and you want to rebuild Ptplot or localize the standalone scripts, then you will need to install the Cygwin toolkit from http://sources.redhat.com/cygwin/

We have packaged up the necessary Cygwin tools and made them available at http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/cygwin.htm. If you are running Windows and do not want to install the Cygwin toolkit, then see Using Ptplot under Windows without Cygwin

Below are the installation instructions for Unix and Windows with Cygwin.

Be sure that JDK 1.4.2 is installed, and that javac is in your path.
Untar or unzip the Ptplot distribution.
Note that under Java 1.4.0_01, viewing local applets that have spaces in the path name may fail if the applet tries to download a data file. The workaround is to place the Ptplot distribution in a directory that does not have space in the pathname. For details, see the Troubleshooting Guide.
Set the PTII environment variable to point to the top of the Ptplot tree. Under C-shell, one would do:
```
setenv PTII ~/src/ptolemy/ptplot5.6-alpha
```
Under Cygwin with bash:
```
PTII=c:\\ptolemy\\ptplot5.6-alpha
export PTII
```
cd into the PTII directory:
```
cd "$PTII"
```
(The double quotes are only necessary if $PTII has spaces in it)
Run configure
```
rm -f config.*
./configure
```
Run make install to compile the Java files and create the jar files.
```
make install
```
View the applets by going starting your browser and going to: ptolemy/plot/doc/index.htm
$PTII/bin contains the following scripts

histogram
Start up a histogram
ptplot
Start up the plotter that understands PlotML
pxgraph
Start up a plotter that understands the older xgraph syntax.
For details about starting up Ptplot by hand, see How do I create a simple standalone Plot application?

InstallAnywhere Installer

Ptplot is also available in several self-extracting formats that were created with InstallAnywhere.

Note that under Java 1.4.0_01, viewing local applets that have spaces in the path name may fail if the applet tries to download a data file. The workaround is to place the Ptplot distribution in a directory that does not have space in the pathname. For details, see the Troubleshooting Guide.

Note that when you run the installer under Windows, Ptplot is added to your Start menu under Ptolemy -> Ptplot 5.6-alpha.

Notes about building and installing

How does configure work?

configure is a /bin/sh script that determines some information about your environment and then modifies a few files. When the configure script is run, it reads in mk/ptII.mk.in and bin/ptinvoke.in generates mk/ptII.mk and bin/ptplot

To get help with configure, try

./configure --help

configure reads in the .in files and substitutes strings inside the @

For example, configure reads in bin/ptinvoke.in and sees

PTII_DEFAULT=@PTII_DEFAULT@
PTJAVA_DIR=@PTJAVA_DIR@

becomes

PTII_DEFAULT=/users/cxh/ptII
PTJAVA_DIR=/opt/jdk1.3

Using Ptplot under Windows without Cygwin

Below are the instructions for using Ptplot if you are under Windows and you do not have the Cygwin and have downloaded the tar or zip files.

Set the PTII variable to the top-level directory of the Ptplot tree.
```
C:\ptolemy\ptplot5.6-alpha> PTII=c:\\ptolemy\\ptplot5.6-alpha
```
PTII is used by the standalone ptplot.bat script and other scripts
(The double backslash is necessary because otherwise bash will interpret c:\ptolemy\ptplot5.6-alpha as c:ptolemyptolemy5.6-alpha)
Be sure that java is in your path by running java -version
Add %PTII%\bin to your PATH.
Run ptplot.bat

Usually, it is not necessary to recompile the Ptplot classes, but below are the instructions for recompiling by hand under Windows without Cygwin.

To compile the Ptplot Java classes, they must be in the directory ptolemy\plot.
```
C:\ptolemy\ptplot5.6-alpha> cd ptolemy\plot
```

set your CLASSPATH to ..\..

C:\ptolemy\ptplot5.6-alpha\ptolemy\plot>set CLASSPATH=..\..
C:\ptolemy\ptplot5.6-alpha\ptolemy\plot>echo %CLASSPATH%
..\..

Remove the old Java files and compile them

C:\ptolemy\ptplot5.6-alpha\ptolemy\plot>del  *.class
C:\ptolemy\ptplot5.6-alpha\ptolemy\plot>javac *.java

Run ptplot.bat, which reads %PTII%

C:\ptolemy\ptplot5.6-alpha\ptolemy\plot>ptplot.bat

Installing Ptplot as an applet

Ptplot includes several jar files, which are collections of Java .class files

plotapplet.jar: .class files necessary for simple JDK1.1 browser applets - no pxgraph, no plotml.
pxgraphapplet.jar: .class files necessary for simple JDK1.1 browser applets with pxgraph classes, no plotml. Applets that use the pxgraphargs applet parameter should use this jar file.
plotmlapplet.jar: .class files necessary for PlotML applets - includes com/microstar/xml and the plotml code, but does not include pxgraph, or PlotFrame.
plot.jar: The standard Ptolemy II jar file that includes the ptolemy/plot/*.class files and the class files in plotml and compat. Does not include com/microstar/xml or ptolemy/gui. plot.jar is used by the Ptolemy II build system.
plotapplication.jar: .class files necessary for standalone applications - includes com/microstar/xml, ptolemy/gui and the plotml code, but does not include pxgraph. If plotapplication.jar is present, then it is used by the standalone scripts (ptplot etc.)

The best way to use Ptplot as an applet is to copy the appropriate *applet.jar file into the same directory as your applet, and then to use the archive applet directive. For examples of applet html code, see the demonstrations.

Installing Ptplot as an application

Under Unix and Windows with the Cygwin toolkit, ptplot can be run as three standalone applications:

ptplot - A modern plot application that with a menubar and such.

histogram - A histogram plot application

pxgraph - A plot application that is mostly backward compatible with the older X11 pxgraph program

When configure is run, it substitutes variables inside ptinvoke.in and produced ptplot. The ptplot script is shared between the standalone applications, ptplot determines what name it was called with, and selects the appropriate class accordingly.

If the ptplot script is run, then ptolemy.plot.PlotApplication is run

If the ptplot script is copied to histogram, then ptolemy.plot.plotml.HistogramMLApplication is run

If the ptplot script is copied to pxgraph, then ptolemy.plot.compat.PxgraphApplication is run

Under Unix or Windows with Cygwin, you can use a hard link to create the histogram and pxgraph script:

cd $PTII/bin
ln ptplot histogram
ln ptplot pxgraph

Under Windows in a DOS shell, three .bat scripts are provided: ptplot.bat, histogram.bat and pxgraph.bat

Last Updated: $Date: 2006/09/21 15:30:44 $