Using Eclipse with Metropolis
These instructions assume you are using Eclipse 3.0 under Windows.
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 Metropolis,
so a few changes are necessary.
-
By default, Eclipse rebuilds a project when any change is made
to a file. This will result in thousands of errors when Metropolis
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."
-
Metropolis 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.
Check Out Metropolis from the CVS Repository
Eclipse will manage your metro code tree as a project called
the metro 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: source.eecs.berkeley.edu
Repository path: /home/cvs
Your user name
are given here. To get access to that page, you must be a member of
the "concurrency" group.
ConnectionType
- If you have CVS read only access, select
pserver
- If you have CVS read/write access and have an external ssh
binary installed, select
ext
. The
Cygwin installation can optionally include an appropriate ssh
binary. If you have Cygwin installed, startup bash and type
ssh -v
to see if ssh is installed.
-
extssh
is not recommended because it
uses version 1 of the SSH protocol which is implemented
by a version of ssh that is built in to Eclipse.
SSH V1 is not as likely to be supported as SSH V2.
Note further that if you select extssh
,
then to run cvs from within
Cygwin bash on the same directory tree as the Eclipse tree
you will need to use the -d
option
cvs -d :ext:yourlogin@ic.eecs.berkeley.edu:/projects/hwsw/hwsw/common/src
The -d
option is necessary because the Cygwin bash
cvs
binary does not understand the extssh
protocol
- Click Finish.
- In the CVS Repositories View window, click on the repository and then on
HEAD until you see the
metro
Head.
- Right mouse click on the
metro
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:
metro
- We recommend that you select "Create project at external location:"
and specify a directory you will find easily, such as
C:\metro
, 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.
- Eclipse needs to be told that the root of the Metropolis java
files is
metro/src
, not metro/
, so
right click on the metro icon, select Properties -> Java Build Path ->
Source and hit the 'Add Folder' button.
Expand the metro icon and select 'src', then 'ok'
- In the Java Build Path window, change the 'Default Output Folder'
to
metro/src
, then 'ok'.
- When the 'Setting Build Paths' window comes up:
"The output folder has changed. OK to remove all generated resources
from the old location '/metro'"
click 'Yes'
- There will probably be
several errors reported that are due to the .classpath that was just
created as part of the checkout/project creation process.
Now, go on to the next step: Creating the .classpath and .project files.
There are parts of the metro tree that are not meant to be
compiled, or are meant to be compiled only in certain situations.
However, without specific instructions to exclude parts of the metro tree,
Eclipse will attempt to compile every .java in the project
which typically leads to many, many error messages.
These exclusion instructions are generated by running
$METRO/configure
.
When $METRO/configure
is run, it
reads in $METRO/.classpath.in
substitutes in variables
that are surrounded with @
and generates
$METRO/.classpath
, and
$METRO/src/.classpath
, which will contain the
proper classpath and directories to exclude.
- Start up Cygwin bash.
- Set the METRO variable and export it
METRO=c:/metro
export METRO
Note: Do not do METRO=`pwd`
under Cygwin bash,
as that will set METRO to a path that includes /cygdrive
and Java does not understand the /cygdrive
notation.
- cd to the METRO directory
cd $METRO
- Run configure:
./configure
This will create $METRO/.classpath
-
If you plan on running the Metropolis startup scripts in
$METRO/bin
from within Cygwin bash, you will probably
want to run the following commands within Cygwin bash:
cd $METRO/bin
make
Create Derived Source Files.
- Create MetaModelParser.java by first creating Lexer.java
cd $METRO/src/metropolis/metamodel/frontend/lexer
make
It is ok if the actual compilation fails, what we are trying to do
is generate the MetaModelParser.java file here, we will compile it later.
- In Eclipse, perform a Refresh on the metro project
by Window -> Open Perspective -> Java,
goto the Package Explorer,
right click on the metro icon and select Refresh
This will
cause Eclipse to see the new metro/src/.classpath
and build
the project
The SystemC backend includes C and C++ files that need to be compiled:
cd $METRO/src/metropolis/metamodel/backends/systemc
make
Now, import the Metropolis specific preferences:
The Metropolis project has a number of requirments in the way that Eclipse is configured.
For example, using spaces instead of tabs for indentation purposes.
Eclipse can be configured to meet many of these requirements.
The file $METRO/.eclipse.epf has these configuration settings and should be used to achieve uniformity
amongst Metropolis developers using Eclipse.
The following table shows these settings.
Preferences set by $METRO/.eclipse.epf
Preference |
Value |
Description |
Auto Rebuild on Resource Modification |
false |
Don't rebuild everytime a resource is modified |
Java Editor Spaces for Tabs |
true |
Java Editor will use spaces for indentation, not tabs |
CVS Ignore Files |
*.class, *.jar, *.lnk, alljsimpletests.tcl,
alljtests.tcl |
CVS will ignore these files. Can be overidden on a case by case basis
|
Tcl file Editor |
Text Editor |
Default Editor for .tcl files is Text Editor |
Label Decorations |
CVS, Linked Resources |
Resources under CVS control are labelled with CVS info |
Task Tags Highlight FIXMES |
FIXME |
FIXMEs are highlighted |
To import the $METRO/.eclipse.epf settings
- Window -> Preferences
- Select Import, and then guide the dialog
to
$METRO/.eclipse.epf
.
Below are instructions on how to set up a project by hand.
Note that the Metropolis tree includes .classpath
and .project
files, so rather than
setting up by hand, you might want to try
Using dot files in $METRO to set up.
It is probably faster if you do:
cd $METRO
make clean
before setting up Eclipse.
- Download and install Eclipse from
http://www.eclipse.org
- Start Eclipse.
- Disable auto rebuild with:
Window->Preferences.
Deselect Workbench->"Perform build automatically on resource modification."
Deselect Debug->"Build (if required) before launching"
- File->New->Project. Select 'Java project'. Name it Metropolis.
Deselect 'Use default' and browse to the
metro/src
directory. Finish. You need to use metro/src
because the java tree is rooted there and not in metro
- When asked if you want to shift to the Java perspective, click on Yes.
- Right click on the
Metropolis
icon in the Package Explorer
and select Properties.
select Java Build Path -> Libraries tab ->
Add JARs. Browse to Metropolis/lib/
and select all the jar files by holding down the Control key
and clicking on each jar file. Hit OK, then Finish.
- Exclude some of the larger directories that will not compile.
In the 'Properties for Metropolis' window, select
Source, then expand the Metropolis folder by clicking on the +,
then click on the Exclusion Filter and hit Edit.
Note that the filter paths should have trailing slashes.
**
is specially interpreted.
Click on Add and type in **/CVS/
. Ok
Click on Add and type in **/codeDoc/
. Ok
Click on Add and type in ptolemy/apps/
. Ok
Click on Add and type in vendors/
. Ok
Click on OK to close the Exclusion Filter
Click on OK to close the 'Properties for Metropolis' window.
- In the top level Eclipse window: Project-> Rebuild All.
This setting is in the $METRO/.eclipse.epf
file.
See Import the Metropolis specific preferences
for details.
Before editing any files, adjust the Editor Preference to not
use tabs.
Either import the Metropolis specific preferences or follow
the steps below
- Window ->Preferences
- Expand the Java tree, select 'Code Formatter' and then the Style tab.
- Uncheck 'Insert tabs for indentation, not spaces'.
- Go back to to the Java tree on the left, select
'Editor' and then the Typing tab.
Check 'InsertSpace for tabs (see Code Formatter preference page)
- Click Ok
This setting is in the $METRO/.eclipse.epf
file.
See Import the Metropolis specific preferences
for details.
- Window -> Preferences -> Team -> CVS -> Ignored
Resources
- Add
*.class
and *.jar
The semantics seem to be ignore .jar files that are not already part of CVS.
This can be overridden on a case by case base if new .jar files get created
that need to be part of CVS.
This setting is not in the $METRO/.eclipse.epf
file.
In the initial default settings, when you double click on a .tcl file
it tries to execute it.
The fix is:
- Window ->Preferences: expand the Workbench tree, select
'File Associations'
- In the 'File types:' section, hit Add and enter
*.tcl
, then hit OK
- In the 'Associated editors' section, hit Add
and select the Text editor, then hit OK.
Also, if you check in a .tcl
file with the wrong association, then it will be checked in in binary mode (-kb
), and
under Solaris, you will get strange test failures.
To fix this, first set up your File Association Preferences
as per the above.
To fix the file under Solaris:
cvs admin -kv Foo.tcl
dos2unix Foo.tcl tmp.tcl
mv tmp.tcl Foo.tcl
cvs commit -m "Got rid of binary chars" Foo.tcl
Eclipse can be set up to hightlight FIXMEs:
- Window -> Preferences ->
- Expand the Java tree, select 'Task Tags'
- Select New and then add FIXME as a Normal priority task.
After installing (unzipping) the Eclipse install into a directory
(e.g., c:\eclipse), the workbench is started by running the Eclipse
executable found in the top-level install directory. The file is
eclipse.exe on Windows systems and simply eclipse on Linux
systems. Note, the following discussion details the setup on Windows
systems. The Linux setup is analogous.
If you don't specify differently, the platform creates a default
workspace directory as a sibling of the executable (e.g.,
c:\eclipse\workspace). This workspace directory is used as the
default content area for your projects as well as for holding any
required metadata. For shared or multi-workspace installs you should
explicitly state the location of your workspace rather than using the
default. There are two ways to control the location of your
workspace; using the current working directory or using the -data
command line argument.
Perhaps the easiest way of using the current working directory is
to create a shortcut using the following steps:
- Navigate to eclipse.exe in the Windows Explorer and using a right
button drag, create a shortcut to eclipse.exe.
- Edit the properties of the shortcut such that the "Start in:" box
identifies the location of your workspace (e.g., c:\myworkspace).
- Close the properties dialog and double-click on the shortcut.
Of course you can get the same effect using a command prompt by
changing directory to your workspace directory and then running
eclipse.exe.
To use the -data command line argument, simply add -data <your
workspace location> (e.g., -data c:\myworkspace) to the "Target:"
line in the shortcut or include it explicitly on your command prompt
command line.
Before editing any files, follow the steps in
Don't use tabs in the editor below
- 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 Metropolis 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.
Resources:
Syncronizing 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.metro.dir=your PtII directroy
(E.g. -Dptolemy.metro.dir=c:\hyzheng\metro
)
- Select Local directory, browse to the directory containing the tcl
tests.
(E.g. C:\hyzheng\metro\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
Eclipse 3.x seesm to also have a .config
directory
that is generated when Eclipse is first run. So, if you are really
stuck, you can remove the .config
directory as well
if it is present.
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 metro/ptolemy/domains/fsm/demo/ABP/img/Receiver.vsd
U metro/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 $METRO/.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 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.