Using Eclipse with Metropolis

These instructions assume you are using Eclipse 3.0 under Windows.

Contents of this page:

  • Install Eclipse
  • Set up Eclipse for Ptolemy II
  • Using Eclipse
  • Optional Extensions
  • Troubleshooting
  • Install Eclipse

    1. Download the latest version of Eclipse from http://www.eclipse.org.
    2. Unzip the download file into an appropriate place (such as C:\Program Files).
    3. 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.

    Set up Eclipse for Metropolis

    Eclipse Preferences for Metropolis

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

    1. 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:
      1. Select Window -> Preferences.
      2. Highlight Workbench (probably already highlighted).
      3. Deselect "Build automatically."

    2. 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:
      1. Select Window->Preferences in the menu.
      2. Expand the Java tree, select "Editor" and then click on the "Typing" tab at the right.
      3. Check "Insert spaces for tabs (see Code Formatter preference page)".
      4. 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:

    1. Set up the CVS connection:
      1. Expose the CVS repositories view by selecting Window->Show View->Other in the menus. Then select CVS->CVS Repositories.
      2. 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
      3. Click Finish.

    2. In the CVS Repositories View window, click on the repository and then on HEAD until you see the metro Head.

    3. Right mouse click on the metro Head, then Select the "Check Out As..." option. Follow the wizard, creating selections as follows:

    4. 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.

    5. 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.
    6. 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'
    7. In the Java Build Path window, change the 'Default Output Folder' to metro/src, then 'ok'.
    8. 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'
    9. 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.

    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.
    1. Start up Cygwin bash.
    2. 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.
    3. cd to the METRO directory
      cd $METRO
      
    4. Run configure:
      ./configure
      
      This will create $METRO/.classpath
    5. 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.
    1. 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.
    2. 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

    Compiling C libraries

    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:

    Importing 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
    1. Window -> Preferences
    2. Select Import, and then guide the dialog to $METRO/.eclipse.epf.

    Setting up for Metropolis By Hand

    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.
    1. Download and install Eclipse from http://www.eclipse.org
    2. Start Eclipse.
    3. Disable auto rebuild with: Window->Preferences. Deselect Workbench->"Perform build automatically on resource modification." Deselect Debug->"Build (if required) before launching"
    4. 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
    5. When asked if you want to shift to the Java perspective, click on Yes.
    6. 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.
    7. 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.
    8. In the top level Eclipse window: Project-> Rebuild All.

    Don't use tabs in the editor

    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

    1. Window ->Preferences
    2. Expand the Java tree, select 'Code Formatter' and then the Style tab.
    3. Uncheck 'Insert tabs for indentation, not spaces'.
    4. 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)
    5. Click Ok

    Ignore .class and .jar files

    This setting is in the $METRO/.eclipse.epf file. See Import the Metropolis specific preferences for details.
    1. Window -> Preferences -> Team -> CVS -> Ignored Resources
    2. 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.

    Associating the Text editor with .tcl files

    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:

    1. Window ->Preferences: expand the Workbench tree, select 'File Associations'
    2. In the 'File types:' section, hit Add and enter *.tcl, then hit OK
    3. 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
    

    Task Tags Highlight FIXMES

    Eclipse can be set up to hightlight FIXMEs:
    1. Window -> Preferences ->
    2. Expand the Java tree, select 'Task Tags'
    3. Select New and then add FIXME as a Normal priority task.

    Using Eclipse

    Running Eclipse

    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:

    1. Navigate to eclipse.exe in the Windows Explorer and using a right button drag, create a shortcut to eclipse.exe.
    2. Edit the properties of the shortcut such that the "Start in:" box identifies the location of your workspace (e.g., c:\myworkspace).
    3. 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.

    Simple Debugging Session

    Before editing any files, follow the steps in Don't use tabs in the editor below
    1. 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
    2. 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.
    3. Press the Run button
    4. 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.

    Using CVS

    Resources:

    Syncronizing with the repository

    1. In the Navigator view scroll/open until you see the resource (directory or file) to be synchronized.
    2. Right click that resource and select Team->Synchronize With Repository...
    3. The Synchronize view should then be visible.
    4. Select the Incoming, Outgoing, or Incoming/Outgoing menu bar icon as appropriate

    Restoring a file from the repository

    1. In the Navigator view scroll/open until you see the resource (directory or file) to be restored.
    2. Right click that resource and select Replace With->Latest From Head.

    Debugging Tcl Tests

    1. Go to Windows -> Open Perspective -> Java.
    2. In Package Explorer, locate ptjacl.jar -> tcl.lang -> Shell.class -> Shell and highlight it.
    3. Go to Run -> Debug...
    4. Select Arguments tag.
    5. In Program arguments, put alljtests.tcl or any individual test tcl file.
      (E.g. SimpleDelay.tcl)
    6. In VM arguments, put -Dptolemy.metro.dir=your PtII directroy
      (E.g. -Dptolemy.metro.dir=c:\hyzheng\metro)
    7. Select Local directory, browse to the directory containing the tcl tests.
      (E.g. C:\hyzheng\metro\ptolemy\domains\de\lib\test)
    8. 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.

    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

    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.

    CVS Console

    You might find the cvs console to be of use, to use it do Window -> Show View -> Other -> CVS -> CVS Console.

    Problems with CVS compression

    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.