OpenPTC 1.0 Java Distribution Installation
------------------------------------------


1) Get the JDK 1.1.6 from www.java.sun.com

Its the official java compiler and its free to download and use.
What more could you ask for? =)

Dont bother with other java compilers, IDE's etc. In my humble
opinion they are next to useless (apart from nice syntax colors
in developer studio with visual j++ :)

IMPORTANT: Do *NOT* get JDK 1.2 (Java 2). Under JDK 1.2 you will
experience a severe performance loss (10x slower than JDK 1.1.6).
Until sun fixes this problem in the JDK 1.2 implementation, you
should advoid JDK 1.2 like the plague!


2) Setup the CLASSPATH environment variable

Once you have the JDK installed, you will have to add the source
directory to your classpath environment variable before you can
start using PTC:

for example, under a command prompt in win32 you would go:

 set CLASSPATH=C:\ptc\java\source;.

if you had installed ptc java to the directory "C:\ptc\java".

Note that the directory "." was also added to the classpath, to
make sure that java will always search the current directory
for class files. this is very important! without it you will
have major trouble running your own java programs :)

Of course, for convenience you will want to add CLASSPATH setting
code to your autoexec.bat, or your systems equivalent to avoid
having to set it everytime you want to use ptc for java :)


3) Compile and run the example programs

Now, once you have the classpath setup you are free to compile
the example programs. To compile and run the "Random" example
program you would do the following: 

(assuming command prompt under win32...)

 c:
 cd ptc\java\examples\Random
 javac Random.java -O
 java Random

"javac" compiles the source "Random.java" into a classfile
(Random.class), with optimizations turned on ("-O"). The next
command... "java Random" runs the class "Random.class" you just
compiled, and you should have a nice little window popup with
some random pixels in it.

The nice thing about java is that all of the ptc source code
is automatically compiled when you compile the examples. Its
like java has a make utility built in to the compiler. There 
is no need to manually compile all the ptc source files.


4) Running the "Applet" example

In the the case where an applet is built your CLASSPATH does not
apply, the browser just searches the current directory for ptc
classfiles.

This means that in order to run a PTC java applet you need to copy
the directory tree of ptc class files into the example directory
otherwise the browser will not be able to load the ptc classes.

In the case of the "Applet" example, you need to copy all of the
*.class files from "source/ptc" to "examples/Applet/ptc". Make
sure you copy all of the subdirectories under ptc over as well.

Once you have done this (and Applet.java has been compiled to a
class file with "javac Applet.java -O") you can load the file
"Applet.html" into your favourite browser, and you should see
random pixels filling an area of the web page.

If this does not work, chances are that your web browser only
supports Java 1.0. This is still quite common as netscape 4.5
and below only support Java 1.0. I suggest you upgrade your
browser to one that supports Java 1.1.

If you want to use PTC and make applets that support java 1.0
you should use "tinyptc" instead of the full PTC for Java...


5) Running the "Tiny" example

There is a special cut down version of PTC for java specially
designed for use in applets. When compiled the classfiles are
only 6k (compared to about 60k+ for full ptc). And the best
thing is that "tinyptc" only uses Java 1.0 so it can be run on
*any* browser that supports java.

The "Tiny" example shows you how to make an applet using tinyptc.
Its does exactly the same thing as the "Applet" example above,
except that you dont have to copy over all the "source/ptc"
class files to get it to work, instead copy over the files in
"source/tinyptc" and then it will work.

If you plan to make applets with PTC i highly recommend using
tinyptc instead of the normal ptc for java.


6) Running the demos

The demos have been setup to work as both java apps and applets.
If you run the demo as a java application, then everything will
work just as for normal examples as in step 3. However, if you
want to run the demos as applets (ie. by running the HTML) you
will have to copy over the classfiles to the demo directly, as
in step 4 otherwise the demo will not run!


7) I cant get it to work! HELP!!!

If you have any problems with java PTC you can use the newsgroups
at news.scene.org/coders.ptc for help. Ask a question here and you
are sure to get help very quickly!



Enjoy!
--
Glenn "Gaffer" Fiedler
ptc@gaffer.org
