Eclipse

Contents

  • Downloading, and installing Eclipse
  • Setting up Eclipse to manage your Ptolemy II development environment
  • If you don't want to use CVS with Eclipse
  • If you do want to use CVS with Eclipse
  • Creating the .classpath and .project files
  • Importing the Ptolemy II specific preferences
  • Setting up for Ptolemy II By Hand
  • Don't use tabs in the editor
  • Proper Handling of Assert Statements
  • Using Eclipse
  • Running Eclipse
  • Simple Debugging Session
  • Using CVS
  • Debugging Tcl Tests
  • Troubleshooting

  • Downloading, and installing Eclipse

    1. Download the latest Release version of Eclipse from http://www.eclipse.org.
      In March 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.
    2. 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).
    3. IMPORTANTIf you plan on using Eclipse with a cvs server later than cvs-1.11.7, you will need to install cvs.jar. See Eclipse 2.1.2 does not work with cvs 1.11.7.
    4. 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.
    5. As an option, you may want to make a shortcut to eclipse.exe.

    Setting up Eclipse to manage your Ptolemy II development environment

    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.

    If you don't want to use CVS with Eclipse

    You must already have a ptII development tree. All you want to do is
    1. Configure the .classpath and .project files. See Creating the .classpath and .project files.
    2. Create the ptII project

    If you do want to use CVS with Eclipse

    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 ptII project in Eclipse under CVS control requires an unusual procedure. In brief, the CVS ptII 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.

    1. Determine where the ptII tree will be put. If you currently have a ptII tree at that location, it must be removed.
    2. Start Eclipse
    3. Set up the CVS connection:
      1. Expose the CVS Repositories View by Window->Show View->Other. The select CVS->CVS Repositories
      2. In the CVS Repositories Panel right mouse click and select New->Repository Location:
        Host: gigassource.eecs.berkeley.edu
        Repository path: /home/cvs
        User: Your username, see http://www.gigascale.org/ptexternal for information about how to get a login for cvs access
        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:gigasource.eecs.berkeley.edu/home/cvs_chess
          The -d option is necessary because the Cygwin bash cvs binary does not understand the extssh protocol
      3. Click Finish.
    4. 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.
    5. In the CVS Repositories View window, click on the repository and then on HEAD until you see the ptII Head.
    6. Right click on the ptII Head, then Select the "Check Out As...." option
    7. Go through the various menus to create a Java Project named ptII.
      Don't use the "Default Location". Instead specify the location where you want ptII to go (e.g. c:\ptII).
    8. Click OK, wait for the checkout to finish.
    9. The result should be the ptII project. 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 ptII 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 ptII 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 $PTII/configure. When $PTII/configure is run, it reads in $PTII/.classpath.in substitutes in variables that are surrounded with @ and generates $PTII/.classpath, which will contain the proper classpath and directories to exclude.
    1. Start up Cygwin bash.
    2. Set the PTII variable and export it
      PTII=c:/ptII
      export PTII
      
    3. cd to the PTII directory
      cd $PTII
      
    4. Run configure:
      ./configure
      
      This will create $PTII/.classpath
    5. If you plan on running the Ptolemy II startup scripts in $PTII/bin from within Cygwin bash, you will probably want to run the following commands within Cygwin bash:
      cd $PTII/bin
      make
      
      See the Ptolemy II Installation page for details.
    6. In Eclipse, perform a Refresh on the ptII project by Window -> Open Perspective -> Java,
      goto the Package Explorer,
      right click on the ptII icon and select Refresh
      This will cause Eclipse to see the new ptII/.classpath and build the project
    Now, import the Ptolemy II specific preferences:

    Importing the Ptolemy II specific preferences

    The Ptolemy 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 $PTII/.eclipse.epf has these configuration settings and should be used to achieve uniformity amongst Ptolemy developers using Eclipse. The following table shows these settings.

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

    Setting up for Ptolemy II By Hand

    Below are instructions on how to set up a project by hand. Note that the Ptolemy II tree includes .classpath and .project files, so rather than setting up by hand, you might want to try Using dot files in $PTII to set up.

    It is probably faster if you do:

    cd $PTII
    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 PtolemyII. Deselect 'Use default' and browse to the PTII directory. Finish.
    5. When asked if you want to shift to the Java perspective, click on Yes.
    6. Right click on the PtolemyII icon in the Package Explorer and select Properties. select Java Build Path -> Libraries tab -> Add JARs. Browse to PtolemyII/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 PtolemyII' window, select Source, then expand the PtolemyII 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 Ptolemy II' window.
    8. In the top level Eclipse window: Project-> Rebuild All.

    Don't use tabs in the editor

    This setting is in the $PTII/.eclipse.epf file. See Import the Ptolemy II specific preferences for details.

    Before editing any files, adjust the Editor Preference to not use tabs.

    Either import the Ptolemy II 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

    Proper Handling of Assert Statements

    ptolemy/caltrop/util/IntegerList.java may fail to compile with a message like:
    "Syntax error on token "<=", ";" expected
    
    The solution is to set Eclipse to use Java 1.4 source code compliance.
    1. Window ->Preferences->Java->Compiler->Compliance and Classfiles
    2. Select 1.4
    3. Check Use default compliance settings
    4. Click Ok

    Ignore .class and .jar files

    This setting is in the $PTII/.eclipse.epf file. See Import the Ptolemy II 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 $PTII/.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 Ptolemy II 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:

    Eclipse 2.1.2 does not work with cvs-1.11.7

    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.
  • cvs_jar.zip is a zipped version of the jar because IE sometimes has problems with save-as for jars
  • We unjar'd and rejared the file so as to avoid an error message
  • It is unfortunate that the jar is on the eclipse website in a https: url, because it means we cannot use lynx or wget.
  • 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.
    1. In your eclipse directory, create a .options file:
      org.eclipse.team.cvs.core/debug=true
      org.eclipse.team.cvs.core/cvsprotocol=true
      
    2. 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.

    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.ptII.dir=your PtII directroy
      (E.g. -Dptolemy.ptII.dir=c:\hyzheng\ptII)
    7. Select Local directory, browse to the directory containing the tcl tests.
      (E.g. C:\hyzheng\ptII\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

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

    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.