Using Eclipse with Metropolis
This document is not yet complete . . .
Contents
- Download the latest Release version of Eclipse from
http://www.eclipse.org
.
In November 2003, the Release version of Eclipse was 2.1.2, so for Windows
download the the file eclipse-SDK-2.1.2-win32.zip and for Linux download
be either eclipse-SDK-2.1.2-linux-motif.zip, or
eclipse-SDK-2.1.2-linux-gtk.zip.
- The download file is a zip file that contains the eclipse
directory. Unzip the download file into an appropriate place (such as
c:\Program Files
, or c:\InstalledStuff
).
- 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.
- As an option, you may want to make a shortcut to
eclipse.exe
.
Eclipse will manage your metro code tree as a project called
the metro project. There are two ways to set up the metro 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.
Note that setting up Eclipse to use CVS can be very slow if
you are connected via a slow connection such as DSL. This is in
part because compression does not work well with the CVS client
that is part of Eclipse, see
Problems with CVS compression for details.
So, if you are connected remotely and plan
to use CVS, you might want to check out the tree by hand and
use Eclipse without CVS. If you have a fast connection, then
you might want to use Eclipse with CVS.
Once the metro 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 metro 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 metro project.
- Either untar the development tree or download using cvs.
If you have a cvs account, try:
cvs -d :ext:yourlogin@ic.eecs.berkeley.edu:/projects/hwsw/hwsw/common/src co metro
- Set
$METRO
to the location of the Metropolis tree.
- Configure the .classpath and .project files. See Creating the .classpath and .project files.
- Create some of the source files that are necessary, see
Create Derived Source Files.
- Create the metro project
- File->New->Project. Select 'Java project'. Name it metro.
Deselect 'Use default' and browse to the
metro/src
directory. (We use metro/src
here because
the Metropolis Java tree is rooted metro/src
,
not metro
))
Then hit Finish.
If you have problems, see Troubleshooting
section.
You may need to:
- Remove
$METRO/src/.classpath
:
rm $(METRO)/src/.classpath
- Remove
eclipse/workspace
- Create the metro project inside eclipse as above
- Recreate the
metro/src/.classpath
file:
cd $METRO
./configure
- Refresh the metro project.
When asked if you want to shift to the Java perspective, click on Yes.
You must start fresh and allow Eclipse to perform the CVS checkout.
Eclipse assumes that an Eclipse project (including the .classpath, and
.project) are under CVS control. Therefore, creating the metro project
in Eclipse under CVS control requires an unusual procedure.
In brief, the CVS metro module must be checked out of CVS into an
Eclipse project that doesn't work "correctly" until the .classpath is
created by manually running configure.
- Determine where the metro tree will be put. If you currently have a
metro tree at that location, it must be removed.
- Start Eclipse
- Set up the CVS connection:
- Expose the CVS Repositories View by Window->Show View->Other. The select CVS->CVS Repositories
- In the CVS Repositories Panel right mouse click and select New->Repository Location:
Host: ic.eecs.berkeley.edu
Repository path: /projects/hwsw/hwsw/common/src
User: Your username
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.
- 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 on the repository and then on
HEAD until you see the
metro
Head.
- Right click on the
metro
Head,
then Select the "Check Out As...." option
- Go through the various menus to create a Java Project named
metro.
Don't use the "Default Location". Instead specify the location
where you want metro to go, for example c:\metro
(Note that we will tell Eclipse that the Java files are rooted at
metro/src
later).
- Click OK, wait for the checkout to finish.
- The result should be the metro project.
- 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.