Setting up Ptolemy II and Eclipse
They assume you are using Eclipse 3.0 under Windows.
Other ways of setting up and building Ptolemy II are described on the
Ptolemy II install page. Contents of this page:
-
Download the latest version of Eclipse from
http://www.eclipse.org.
-
Unzip the download file into an appropriate place (such as
C:\Program Files
).
-
Finish the installation by running
eclipse/eclipse.exe
.
The first time this is run it will complete the installation process.
After the first run, normal start-up will occur whenever it is started.
The default configuration of Eclipse has some difficulties with Ptolemy II,
so a few changes are necessary.
-
We will need to change the default memory size for Eclipse
because Ptolemy II is a big project.
In Windows, create a shortcut to eclipse.exe on your desktop.
Then right mouse click on the shortcut and select Properties and change
the target to increase the memory allocated by default. E.g.,
if you installed Eclipse in
C:\Program Files\eclipse3.0
,
then the Target should read:
"C:\Program Files\eclipse3.0\eclipse.exe" -vmargs -Xmx256M
The maximum memory size will now be 256 megabytes when you restart
Eclipse.
-
Ptolemy II uses some features of Java 1.4.
Set Eclipse to use Java 1.4 source code compliance.
- Window->Preferences->Java->Compiler->Compliance and Classfiles
- Uncheck "Use default compliance settings".
- Set both "Generated .class files compatibility" and
"Source compatibility" to 1.4.
- Click OK.
-
By default, Eclipse rebuilds a project when any change is made
to a file. This will result in thousands of errors when Ptolemy II
is first checked out, and during normal usage, can be annoying because
of the pauses it creates. We suggest disabling this feature as
follows:
- Select Window -> Preferences.
- Highlight Workbench (probably already highlighted).
- Deselect "Build automatically."
-
Ptolemy II source files are worked on by many people with different editors.
Unfortunately, different text editors interpret tab characters differently,
so it is best to use spaces rather than tabs. You can specify for Eclipse
to always do this as follows:
- Select Window->Preferences in the menu.
- Expand the Java tree, select "Editor" and then click on the "Typing"
tab at the right.
- Check "Insert spaces for tabs (see Code Formatter preference page)".
- Click OK.
Eclipse will manage your ptII code tree as a project called
the ptII project. There are two ways to set up the ptII project,
either aware of the CVS aspects, on unaware of the CVS aspects..
Without CVS, you'll need to manage the CVS aspects in the usual way,
i.e. with CVS commands being submitted to a bash shell. With CVS,
Eclipse will do all sorts of things to "help" you. Most of these
things are good, but there is a learning curve.
Once the ptII project has been set up there seems to be no way to
switch between using CVS and not using CVS. I.E., the only way to
switch is to re-create the ptII project. (Actually, this isn't too
hard after you've done it a couple of times :-)). Therefore, you'll
need to decide if you want Eclipse to be aware of, and manage the CVS
aspects of the ptII project.
You must already have a ptII development tree. All you want to do is
- Configure the .classpath and .project files. See
.classpath.default
. below.
- Create the ptII project
- File->New->Project. Select 'Java project'. Name it ptII.
Deselect 'Use default' and browse to the PTII directory. Finish.
- When asked if you want to shift to the Java perspective, click on Yes.
Check Out Ptolemy II from the CVS Repository
Eclipse will manage your ptII code tree as a project called
the ptII project. Assuming Eclipse is running:
- Set up the CVS connection:
- Expose the CVS repositories view by selecting
Window->Show View->Other in the menus.
Then select CVS->CVS Repositories.
- In the CVS Repositories Panel, right mouse click
and select New->Repository Location:
Host: gigasource.eecs.berkeley.edu
Repository path: /home/cvs/cvsanon
The user name and password
are given in
http://embedded.eecs.berkeley.edu/concurrency/private/4.html
. To get access to that page, you must be a member of
the "concurrency" group, which means that you are taking
the UC Berkeley EECS 290n class.
and
http://chess.eecs.berkeley.edu/ptexternal/private/2.html
To have permission to access that page, you much be a member
of the ptexternal
workgroup. (Currently, membership
is only available to active participants in the project).
Or, if you have an individual read/write
CVS account on gigasource, you can use your gigasource user name
and password.
- Select
pserver
.
Note: Most users will select pserver
because
they will be accessing the tree with read-only CVS access.
If you have an individual read/write CVS account on gigasource,
then select extssh
. See the
Ptexternal page
for details.
- Click Finish.
- If you are connecting via a DSL connection, you may
want to use compression to transfer files:
In Window -> Preferences -> Team -> CVS, change Compression Level
to 3. Under Eclipse 2.1, compression level 9 might not work, see
Problems with CVS compression for details.
- In the CVS Repositories View window, click + sign to the left of the repository and then on the + sign to the left of HEAD until you see the
ptII
Head.
- Right mouse click on the
ptII
Head,
then Select the "Check Out As..." option. Follow the wizard,
creating selections as follows:
- Check out as a project configured using the New Project Wizard
- Java project
- Name of the project:
ptII
- We recommend that you select "Create project at external location:"
and specify a directory you will find easily, such as
C:\ptII
, rather than the default, which is within the
Eclipse workspace directory.
- Click Finish.
- Wait for the checkout to finish. Go get coffee.
Note:If you did not disable build automatically, as
suggested above, then Eclipse will build the project and produce
thousands of errors. This is not really a problem. You will
fix the errors below with the .classpath.default
file.
- You will want to view the project in the Java perspective.
If you aren't already in the Java perspective, select
Window->Open Perspective->Java in the menu.
By default, Eclipse offers a "package explorer" as the main navigation
mechanism for the source files. I much prefer to use the "navigator."
To get the navigator, select
Window->Show View->Navigator in the menu.
You can now browse the source files.
- Find
the file in the ptII home directory called
.classpath.default
and copy it into a new file called
.classpath
.
- In Eclipse, perform a Refresh on the ptII project
by Window->Open Perspective->Java,
Go to the Package Explorer or the Navigator.
Right mouse click on the ptII icon and select Refresh.
Note:If you do not do copy .classpath.default
and select "Refresh", then Eclipse will produce
thousands of errors. This is not really a problem. It reflects
that you probably don't have installed many optional packages that
are needed to build subsets of Ptolemy II. You can ignore the errors
(not advised, since they will mask errors you make), or you can copy
the .classpath.default
file and rebuild.
Alternatively, you can install
the optional packages and run configure.
- Build Ptolemy II by selecting Project -> Build All.
You will get many warnings that you can ignore, but hopefully no errors.
- In the Run menu, select "Run...".
- In the resulting dialog, select "Java Application" and click "New".
- In the dialog, fill in the boxes as follows:
- Name:
Vergil
- Project:
ptII
- Main class:
ptolemy.vergil.VergilApplication
- Press the Run button.
The Ptolemy II welcome window should appear.
You may now wish to read the Using Vergil
tutorial.
Ptolemy II includes a number of packages that rely on software that you may
or may not have installed, such as MATLAB, the Java comm package (for serial
port connections), joystick support, Java Advanced Imaging (JAI), the Java
Media Framework (JMF), and Java 3D. If you wish to use or extend these
features, you will need to perform a few extra steps. These steps
require execution of a script called "configure" in the Ptolemy II
home directory, which in turn requires (on Windows) installation of
Cygwin, a package that offers Unix-like facilities within Windows.
You can find instructions for installing Cygwin at
http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/cygwin.htm.
The procedure below will modify the .classpath file that is
provided in the CVS repository to customize it for
the software that you have installed.
The procedure is as follows:
- Start up Cygwin bash shell.
- Set the PTII variable and export it
PTII=c:/ptII
export PTII
-
cd to the PTII directory
cd $PTII
- Run configure:
./configure
This will create $PTII/.classpath
-
If you plan on running the Ptolemy II startup scripts in
$PTII/bin
on the command line, you will probably
want to run the following commands within Cygwin bash:
cd $PTII/bin
make
- In Eclipse, perform a Refresh on the ptII project
by Window->Open Perspective->Java,
Go to the Package Explorer or the Navigator.
Right mouse click on the ptII icon and select Refresh.
This will
cause Eclipse to see the new ptII/.classpath
and to build
the project (or you may have to manually rebuild if you turned
off automatic rebuild).
Resources:
Note that Eclipse 2.1.2 does not work with cvs-1.11.7, you must
download and install cvs.jarWhy doesn't Eclipse 2.1.x work with CVS server versions 1.11.7 and beyond? says:
Most of the interesting Eclipse CVS functionality relies on the format
of the messages and the change in format made in 1.11.7 breaks the
parsing in 2.1.x.
See bug 45138
for more information on this issue.
That bug says that a fix is to download cvs.jar
https://bugs.eclipse.org/bugs/attachment.cgi?id=6491&action=view
and:
However, under Internet Explorer, you might not be able to
download an uncorrupted version of the jar. Instead go to
http://ptolemy.eecs.berkeley.edu/~cxh/eclipse/
and right click on
cvs_jar.zip
and select Save Target As
.
Debugging CVS
http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-vcm-home/docs/online/cvs_features2.0/cvs-faq.html#misc_0
has instructions about how to enable debugging for cvs.
- In your eclipse directory, create a
.options
file:
org.eclipse.team.cvs.core/debug=true
org.eclipse.team.cvs.core/cvsprotocol=true
- Start up eclipse
./eclipse -vm c:/j2sdk1.4.2_03/jre/bin/java.exe -debug -consolelog
Note that it is important that you run the jre version of java and not javaw.
Synchronizing with the repository
- In the Navigator view scroll/open until you see the resource
(directory or file) to be synchronized.
- Right click that resource and select Team->Synchronize With Repository...
- The Synchronize view should then be visible.
- Select the Incoming, Outgoing, or Incoming/Outgoing menu bar icon as appropriate
Restoring a file from the repository
- In the Navigator view scroll/open until you see the resource (directory or file) to be restored.
- Right click that resource and select Replace With->Latest From Head.
- Go to Windows -> Open Perspective -> Java.
- In Package Explorer, locate ptjacl.jar -> tcl.lang ->
Shell.class -> Shell and highlight it.
- Go to Run -> Debug...
- Select Arguments tag.
- In Program arguments, put alljtests.tcl or any individual test tcl file.
(E.g. SimpleDelay.tcl)
- In VM arguments, put
-Dptolemy.ptII.dir=your PtII directory
(E.g. -Dptolemy.ptII.dir=c:\hyzheng\ptII
)
- Select Local directory, browse to the directory containing the tcl
tests.
(E.g. C:\hyzheng\ptII\ptolemy\domains\de\lib\test
)
- Select Debug.
The nice thing of using Eclipse is that you can very easily locate where
the exception is thrown by clicking the classes listed in the stack trace.
You may further register a breakpoint to do more diagnosis.
Preferences
If you have already used Eclipse and you would like to start over with
new projects and preferences, remove the workspace
directory in the
Eclipse directory. The workspace
directory will only
appear if you have already run Eclipse. Note that removing the
workspace
directory will cause Eclipse to 'forget'
about any projects that you may have set up
You might find the cvs console to be of use, to use it do
Window -> Show View -> Other -> CVS -> CVS Console.
If, under Eclipse 2.1, you receive a message "Terminated with fatal
signal 10", then try using a different compression level, see the
The Eclipse CVS FAQ
for details.
https://bugs.eclipse.org/bugs/show_bug.cgi?id=15724
suggests using
a compression level of 5.
After the failure, the cvs log (Window -> Show Views -> CVS -> CVS Console says:
U ptII/ptolemy/domains/fsm/demo/ABP/img/Receiver.vsd
U ptII/ptolemy/domains/fsm/demo/ABP/img/Sender.gif
Terminated with fatal signal 11
The server reported an error while performing the "cvs checkout" command. (took 15:16.607)
Error: : Terminated with fatal signal 11
***
Rebuilding Briefly flashes a window
If you have problems where clicking on build briefly flashes up
a window, look in $PTII/.classpath
for and empty
exclusion that looks like ||
If you have problems with the classpath, look in the
workspace/.metadata/log
file that is in
the directory where eclipse is installed. For more information
about the .metadata
directory, see
below.
Ignore files
To ignore files from within CVS:
Windows -> Preferences -> Team -> -> Ignored Resources
Add the following to Ignore Patterns
Eclipse takes a long time to start up
If Eclipse takes a long time to start up, then the problem could be that
Basically, when eclipse starts up, it might try to update
H:/workspace/.metadata
. The solution is covered in
http://www.eclipse.org/documentation/html/plugins/org.eclipse.platform.doc.user/doc/tasks/running_eclipse.htm
:
The way I figured this out was by running Norton Antivirus and
doing View -> File System Realtime Scan Statistics and then I noticed
that my machine was updating H:/workspace/.metadata
I think I introduced the problem by clicking on the Eclipse.exe
binary and selecting Pin to Start Menu. My solution was to remove the
Eclipse bogus entry in the start menu and then create a shortcut,
change Start in property and then pin that shortcut to my start menu.
Running Eclipse under JDK1.4 on an IBM T30
If you are running on an IBM T30 laptop with JDK1.4, and
your machine locks up upon exiting an application, then
you may
need to invoke java with the -Dsun.java2d.d3d=false
argument.
The way to do this is to do
Run
0> Debug ...
-> Arguments
and then add -Dsun.java2d.d3d=false
to the
VM arguments
text area.