Setting up Ptolemy II and Eclipse

These are simplified instructions for setting up Eclipse using the source tree. See eclipse.htm for instructions about how to set up Eclipse using the Subversion version control system. Subversion allows you to get updates from the Ptolemy development tree. The instructions here provide access to a static source code tree, such as what is shipped with the Ptolemy II release.

These instructions assume you are using Eclipse Helios under Windows or Mac OS X. Other ways of setting up and building Ptolemy II are described on the Ptolemy II install page.

Contents of this page:

Install Eclipse

Eclipse Preferences for Ptolemy II

Set up Eclipse for Ptolemy II

Eclipse is unaware of the version control aspects of the project.

Simple Debugging Session

Optional Extensions

Troubleshooting

Install Eclipse

Download the latest version of Eclipse from http://www.eclipse.org.
In October, 2010, we chose Eclipse for RCP and RAP Developers, which is 190Mb. The Eclipse for RCP and RAP Developers version includes the plug-in development environment (PDE), which is needed by the backtrack facility, which is an optional part of Ptolemy II that allows models to restore their old state. If the version of Eclipse that you install does not have the PDE, then there will be build errors, which can be fixed by excluding ptolemy/backtrack/ from the build.
Eclipse is available as both 32-bit and 64-bit binaries. Deciding which one to download can be complex.

The basic idea is that to use a 64-bit version of Eclipse, you must have a 64-bit JVM and an operating system that will support 64-bit applications. When in doubt, choose the 32-bit version of Eclipse, it is more likely to work than the 64-bit version.

See below for details.

32-bit or 64-bit?
- (Linux): Run uname -a. If the result contains x64, you are running a 64-bit version of Linux and would select the 64-bit version of Eclipse.. Also, try java -version. Below is a run on a 64-bit Linux machine:
```
-bash-3.2$ uname -a
Linux sisyphus.eecs.berkeley.edu 2.6.18-164.11.1.el5xen #1 SMP \
 Wed Jan 6 13:43:33 EST 2010 x86_64 x86_64 x86_64 GNU/Linux
-bash-3.2$ java -version
java version "1.5.0_22"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_22-b03)
Java HotSpot(TM) 64-Bit Server VM (build 1.5.0_22-b03, mixed mode)
```
- (Mac OS X): Under Mac OS X 10.5 and 10.6, the default JVM is 1.6, which is 64-bit. However, Java 1.6.0_20 does not work well. The issue is that the following stack trace appears:
```
2010-10-10 11:50:02.263 java[7823:613] java.lang.NullPointerException
at apple.awt.CToolkit.postEvent(CToolkit.java:1086)
at apple.awt.EventFactoryProxy.forwardEvent(EventFactoryProxy.java:53)
```
  The bug happens when running from Eclipse or from the command line. The bug requires UI interactions such as mouse movement or clicking. The bug is probably a threading bug and may only show up on multi-core machines. The downside is that when the bug occurs, the debugging session in Eclipse may become non-responsive.
  For further information, see: http://lists.apple.com/archives/java-dev/2010/May/msg00140.html.
  So, at this time, we are recommending the 32-bit version with Java 1.5.
  Download eclipse-rcp-helios-SR1-macosx-cocoa.tar.gz uncompress it and move eclipse/ into /Applications, which will create /Applications/eclipse/Eclipse.app.
  Firefox Mac OS X Details:
  1. Firefox will download the file into a directory, which may be /Downloads
  2. Double click on eclipse-rcp-helios-SR1-macosx-cocoa.tar.gz which will create the eclipse directory.
  3. Drag the eclipse directory to your Applications directory.
  The next step on the Mac is to force Eclipse to use Java 1.5 by editing eclipse.ini.
  1. In the Finder, go to /Applications/eclipse, find the Eclipse executable and right click (Control + click) and choose "Show Package Contents".
  2. Browse to Contents/MacOS and double click on eclipse.ini, which will open up the file in TextEdit
  3. Edit the file and insert -vm /System/Library/Frameworks/JavaVM.framework/Versions/1.5/Home/bin/java
    before the -vmargs line.
  4. Save the file and exit TextEdit.
  For details about eclipse.ini, see http://wiki.eclipse.org/Eclipse.ini
  When you start up Eclipse, if you want to verify which version of Java you are running
  - (Mac OS X): Eclipse | About Eclipse | Installation Details | Configuration.
    For Java 1.5, the java.class.version property should be 49.0.
    For a 64-bit JVM, the java.vm.name property might have the string 64 in it.
- (Windows): Determine whether you are running a 32-bit or 64-bit version of the OS.
  - Windows 7 or Vista: "Start", then right click on "Computer", then click on "Properties". Under System, you should see the system type. The 64-bit version of Windows 7 will say "64-bit Operating System". See http://windows.microsoft.com/en-US/windows7/32-bit-and-64-bit-Windows-frequently-asked-questions. for details.
  - Windows XP: "Start", then right click on "My Computer", and then click on "Properties". Under "System", if you see "x64 Edition", then you are running a 64-bit version of Windows. If "x64 Edition" is not listed, then you are running a 32-bit version of Windows.
  After determining whether to download the 32-bit or 64-bit version of Eclipse, download the file and unzip the download file into an appropriate place, such as C:\Program Files, which will create C:\Program Files\eclipse\eclipse.exe.
  If eclipse\eclipse.exe is not created, then it could be that the security policy on your machine is preventing the creation of .exe files. If this is the case, then try right clicking on the zip file, select "Properties" and then at the bottom, hit "Unblock" and then "Apply". Or try running unzip from the command line.
(All Platforms): Finish the installation by double clicking on /Applications/eclipse/Eclipse.app or eclipse/eclipse.exe.
The first time this is run it will complete the installation process.
- (Windows): If Eclipse fails to start with the message "Windows cannot access the specified device, path or file. You may not have the appropriate permissions to access the item", then it may be necessary to make eclipse.exe and a dll executable:
```
chmod a+x eclipse.exe
```
  If you get the message "The Eclipse executable launcher was unable to locate its companion shared library", then run the following command in the eclipse directory.
```
find . -name *.dll -exec chmod a+x {} \;
```
  After the first run, normal start-up will occur whenever it is started.

Eclipse Preferences for Ptolemy II

Eclipse has the notion of a workspace, which is a collection of one or more projects. Ptolemy II is a project.
When the "Workspace Launcher" window comes up, either stick with the default or choose a new directory. Note that the projects can be located outside of the workspace directory. One caveat is that Eclipse will not permit the project directory to be a parent of the workspace directory, so placing the workspace in a subdirectory such as the default location is best.
Click "OK" to create the workspace and open Eclipse.
Below is the Workspace Launcher Window:

Eclipse Workspace Launcher

The default configuration of Eclipse has some difficulties with Ptolemy II, so a few changes are necessary.

(Optional): Shortcuts and Memory Size
- (Mac OS X): In Applications/eclipse, drag the Eclipse.app icon to the Finder Dock on the edge of your screen. This will give you fast access to starting Eclipse.
  There is usually no need to set the memory size for Eclipse under Mac OS X. By default, it is set to 512 megabytes. For details about setting the memory size, see: Eclipse Workbench User Guide/Tasks/Running Eclipse.
- (Windows): In Windows, create a shortcut to eclipse.exe by going to the directory where Eclipse is installed, right clicking on eclipse.exe and selecting Create Shortcut.
  To add Eclipse to the start menu, right click on the shortcut and select Pin to Start Menu
  There is usually no need to set the memory size for Eclipse. By default, it is set to 512 megabytes in the eclipse.ini file.
Eclipse requires some customization to build Ptolemy II and to keep the Ptolemy II coding style. In the steps below, we outline changes to be made in the Eclipse Preferences window.
Under Windows the Eclipse Preferences window is invoked via Window | Preferences.
Under Mac OS X the Eclipse Preferences window is invoked via Eclipse | Preferences.
For each of the changes, hit Apply. When all the changes are done, hit OK, which will close the Eclipse Preferences Window. in the preferences window
(Mac OS X: Eclipse | Preferences)
(Windows: Window | Preferences)
Go to Java | Code Style | Formatter and click New
In the "New Profile" Window, for the Profile name, enter "Ptolemy II" Under "Initialize settings with the following profile", select "Java Conventions [built-in]" (We use Java Conventions over the "Eclipse" setting because the Eclipse style uses tabs.) Then hit OK
Under the "Indentation" tab, change the Tab policy to "Spaces only".
Under the "New Lines" tab, select "at end of file"
Under the "Comments" tab,
unselect "Enable Javadoc comment formatting"
unselect "Enable block comment formatting", otherwise the block comments that have <pre> ... <pre> get changed.
unselect "Enable line comment formatting", otherwise the headers for public methods etc. get changed.
Click OK.
In the Preferences Window, click Apply.

Ptolemy II 8.0 uses some features of Java 1.5, which is also known as Java 5.0. In particular, ptolemy/actor/ptalon uses generics, which require Java 1.5 (aka Java 5.0) or later.

However, the Ptolemy II development trunk that includes changes after Ptolemy II 8.0 uses some features of Java 1.6 (aka Java 6.0). In particular, ptdb to uses javax.swing.GroupLayout. which requires Java 1.6 (also known as 6.0) or later.

(Mac OS X): It is best to set Eclipse to use Java 1.5 or 5.0 or later source code compliance.
(Windows): It is best to set Eclipse to use Java 1.6 or 6.0 or later source code compliance.

While still in the preferences window
(Mac OS X: Eclipse | Preferences)
(Windows: Window | Preferences)
expand Java | Compiler
Make sure that Set "Compiler compliance level":
- (Mac OS X): "1.5" or "5.0"
- (Windows): "1.6" or "6.0"
Note that Java 1.5 is the same as Java 5.0 and Java 1.6 is the same as Java 6.0. What we don't want is "1.4" or "4.0". If you plan on using the the Ptolemy II development tree after Ptolemy II 8.0. then you don't want "1.5" or "5.0".
Click Apply.

Eclipse has very good compiler error/warning. One of the warnings complains if a Serializable class does not have serialVersionUID declared. Since this warning is only useful if you are tightly managing serialization, we turn it off:

While still in the preferences window
(Mac OS X: Eclipse | Preferences)
(Windows: Window | Preferences)
Expand Java | Compiler | Errors/Warning
Under "Potential programming problems", change "Serializable class without serialVersionUID" to "Ignore"
Under "Generic Types", change "Unchecked generic type operation" to "Ignore".
Under "Generic Types", change "Usage of a raw type" to "Ignore".
Click Apply. If you are prompted for a full rebuild, click Yes.

(Windows:) The PtDoc Doclet in $PTII/doc/doclets/PtDoclet.java requires tools.jar, which is only in the Java Development Kit (JDK), not the Java Runtime Environment (JRE). So, be sure that a JDK is selected for building, not a JRE.
While still in the preferences window:
(Mac OS X: Eclipse | Preferences)
(Windows: Window | Preferences)

Select Java | Installed JREs
(Mac OS X): select JVM 1.5.0.
(Windows): select JVM 1.6.0.
Verify that the checked line corresponds with a JDK, not a JRE.

(Windows): While in the "Installed JREs" window, under Java 1.6, tools.jar must be added the external jars:

Select the default JRE | Edit | Add External Jars.
Browse to the path of your JDK for example c:\Program Files\Java JDK1.6.0_22\lib
Hit Open, select tools.jar and then finish.

Click OK in the Preferences window to apply all of the above changes.

Setting up Eclipse to manage your Ptolemy II development environment

Eclipse will manage your ptII code tree as a project called the ptII project.

Download a ptII source tree from http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest
The Windows and Mac OS X installers include the source, or you may install a separate source-only download.
Eclipse uses the .classpath file to set paths and exclude files. There are two choices:
1. In the Ptolemy II source tree, copy .classpath.default to .classpath. This choice is the simpler choice, but might exclude optional third party packages.
2. Run ./configure. This choice is more complex, especially for Windows users. However, this choice will include optional third party software that is already installed on your machine.
Choose one of the options below
A. Copy .classpath to .classpath.default
- (Mac OS X): Unfortunately, by default the Mac OS X Finder hides files whose names begin with a period, such as .classpath. One solution is to follow the instructions from: http://www.macworld.com/article/51830/2006/07/showallfinder.html:
  1. Start up the Terminal application, which may be found as /Utilities/Terminal.app. Enter:
```
	   defaults write com.apple.Finder AppleShowAllFiles YES
	 
```
  2. Restart the Finder by holding down the Option key, then clicking and holding on the Finder icon in the Dock. Then, select "Relaunch". Or, log out and log back in again.
  3. Start up the Terminal application, which may be found as /Utilities/Terminal.app
  4. In the Terminal, change to the directory where the Ptolemy II source code was installed. For example:
```
	   cd /Applications/Ptolemy/ptII8.0.1
	 
```
  5. Copy the files:
```
           cp .classpath.default .classpath
         
```
- (Windows):
  1. Find the Ptolemy II source distribution, which by default would be c:\Ptolemy\ptII8.0.1.
  2. Right click on .classpath and select delete.
  3. Right click on .classpath.default, select copy.
  4. Select paste and paste a copy of the file.
  5. Right click on the copy, select rename and rename the file to .classpath.default.
OR

B. Run ./configure
Ptolemy II includes a number of packages that rely on software that you may or may not have installed, such as MATLAB, the rxtx 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 configureThe procedure below will modify the .classpath file that is provided in the version control repository to customize it for the software that you have installed. (Mac OS X): Using the Terminal to run configure Start up the Terminal application, which may be found as /Utilities/Terminal.app In the Terminal, change to the directory where the Ptolemy II source code was installed. For example: cd /Applications/Ptolemy/ptII8.0.1 Set $PTII to the location of the source tree: export PTII=`pwd` Make configure executable. chmod a+x configure Run ./configure ./configure (Windows): Install Cygwin and run configure Unfortunately Windows does not ship with Unix shell commands like make. The workaround is to install Cygwin, see http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/cygwin.htm Start up the Cygwin Bash shell: Start | Run | Cygwin Change to the directory where the Ptolemy II source code was installed. For example: cd c:/Ptolemy/ptII8.0.1 Note that if there are spaces in the path name to the directory where your Ptolemy installation is located, then you should use double quotes around the path: cd "c:/Documents and Settings/yourLogin/workspace/ptII" Set $PTII to the location of the Ptolemy II source tree: export PTII=c:/Ptolemy/ptII8.0.1 Again, if there are spaces in the path, use double quotes: export PTII="c:/Documents and Settings/yourLogin/workspace/ptII" Run: ./configure This will create $PTII/.classpath
If Eclipse is not running, start up Eclipse
In Eclipse, do File | New | Project.
In the "New Project" window, select "Java" > "Java project", Click Next.
In the "New Java Project" window: In "Project Name", enter any project name, ptII is a common choice. Uncheck "Use default location" and browse to the location of the source tree. (Mac OS X): For example, browse to /Applications/Ptolemy/ptII8.0.1 Press "Next". There might be a delay as Eclipse scans your ptII tree. Below is the New Java Project window: Warning: If the "Setting Build Paths" window comes up with a message "The output folder has changed. Do you want to remove all generated resources from the old location ptII/bin", then the problem is that the .classpath file was not found. It is best if you exit Eclipse, create the .classpath file and redo the above steps.
In the "New Java Project" window, select "Allow output folders for source folder", then click "Finish" Below is the second New Java Project window:
When asked if you want to shift to the Java perspective, click on Yes.
The workspace will take a few minutes to build.




Running Ptolemy II


  In the Run menu, select "Run Configurations...".

 
 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.

Simple Debugging Session


  Locate ptolemy/vergil/VergilApplication in the Explorer and
double click. Place a breakpoint on the first line of main()
by using Run | Add/Remove Breakpoint

 
 Tell Eclipse which class to run with Run | Run.
On the Main
tab, select the Ptolemy II package and enter
ptolemy.vergil.VergilApplication as Main class.

 
 Press the Run button
 
 To debug, quit Vergil, and place a breakpoint in, say, the fire() method
of ptolemy.domains.ct.kernel.CTBaseIntegrator. Then Run | Debug, and
as above. Open the Lorenz CT demo from the Quick Tour and run it.
 



Troubleshooting

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

Build Error: Assert cannot be resolved
If, when building, the Problem tab shows "Assert cannot be resolved",
then the problem is that Junit is not being found.

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.

Eclipse takes a long time to start up

If Eclipse takes a long time to start up, then the problem could be 
a problem in your .metadata file.

 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.

Setting up Ptolemy II and Eclipse

Install Eclipse

32-bit or 64-bit?

Eclipse Preferences for Ptolemy II

Setting up Eclipse to manage your Ptolemy II development environment

A. Copy .classpath to .classpath.default

B. Run ./configure

Running Ptolemy II

Simple Debugging Session

Troubleshooting

Preferences

Build Error: Assert cannot be resolved

Rebuilding Briefly flashes a window

Eclipse takes a long time to start up