• View
• Edit
• History
• Print

EclipseAndOSGI

Notes about using Eclipse and OSGI In September, 2008, Hauke Fuhrmann helped us prototype some Eclipse bundles of Ptolemy II.

Resources

• Kepler Developer Frameworks Site, see especially the Links Page
• Ptolemy Package Dependencies Discusses the Ptolemy II 7.0 release, but the overall structure has not changed.

Eclipse How-To's

Note that exactly how we check out triq is up to discussion, see Getting Started Issues

Currently, our work is prototyped in the triq svn repository. This repository consists of a number of Eclipse projects, where each project is a bundle.

Checking out Triq using Project Sets

4/09: Hauke came up with this procedure:

1. Start up Eclipse with a new workspace, or select File -> Switch Workspace and enter the name of a new workspace
2. If necessary, install a Subversion plugin into Eclipse You need only install one or the other of Subversive or Subclipse
   1. Subversive - preferred because it handles multiple repositories
   2. Subclipse - an alternative. See the ptexternal instructions for details.
3. In Eclipse: Window -> Show View -> Other -> SVN ->SVN Repository
4. In the SVN Repository tab: Right Click -> New Repository Location -> Url: svn+ssh://source.eecs.berkeley.edu/chess/triq or @@https://source.eecs.berkeley.edu/svn/chess/triq&& and then hit Finish in the SVN window.
5. In the SVN Repository tab: Expand svn+ssh://source.eecs.berkeley.edu/chess/triq, expand trunk and then Right click on project-sets, select Check Out
6. 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. Many developers 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.
7. In the Package Explorer Tab on the left, expand project-sets, right click on ptiny.psf and select "Import Project Set"
8. Go get coffee

Import the ptolemy.ptiny feature and run

1. In the SVN Repositories pane, Expand svn+ssh://source.eecs.berkeley.edu/chess/triq, expand trunk, expand features
2. Right click on ptolemy.ptiny and select "Find/Check Out As..."
3. In the "Check Out As" Window, click on Finish
4. Select Run -> Run Configurations
5. In the Run Configurations Window, expand Java Application, click on Ptiny and select Run.

Older Triq Procedure

The procedure is that we used to do is:

1. Check out triq
2. Import plugins
3. Import the feature that requires the plugins necessary to run our application
4. Run application

Check out triq

1. Start up Eclipse (for better performance with a lot of graphical stuff give it more memory: eclipse -vmargs -Xmx768M -XX:PermSize=64M -XX:MaxPermSize=256M -Xmn128M (or set these in the eclipse.ini)) FIXME: how to do this on the Mac?
2. If necessary, install a Subversion plugin into Eclipse You need only install one or the other of Subversive or Subclipse
   1. Subversive - preferred because it handles multiple repositories
   2. Subclipse - an alternative. See the ptexternal instructions for details.
3. In Eclipse: Window -> Show View -> Other -> SVN ->SVN Repository
4. In the SVN Repository tab: Right Click -> New Repository Location -> Url: svn+ssh://source.eecs.berkeley.edu/chess/triq and then hit Finish in the SVN window.
5. In the SVN Repository tab: Expand svn+ssh://source.eecs.berkeley.edu/chess/triq, Right click on trunk, select Check Out
6. In the "Checkout from SVN" window, select "Checkout as a project in the workspace", then hit finish
   FIXME Brian says: Use Team Project Sets that allows us to import the whole project sets by downloading the svn.
7. The triq repository will download. Go get coffee.

Import the plug-ins

1. In Eclipse: Window -> Open Perspective -> Java You may need to close the Welcome and SVN Repository Tabs by clicking on the X in the tabs
2. Right click in the Package Explorer pane and select Import
3. In the Select window, expand Plug-in Development -> Plug-ins and Fragments, hit Next.
4. In the Import Plug-ins and Fragments window:
   1. In "Import From", uncheck "The target platform (as specified in the Preferenced")
   2. In "Import From", change Plug-in Location to the location where triq was checked out:
      1. Under Windows, browse to c:/Documents and Settings/yourlogin/workspace/triq
      2. Under Mac OS X, browse to /Users/yourlogin/Documents/workspace/triq
   3. Select Next
5. In the Selection window, select Add All and then Finish

Mac OS X only

Because of a bug in Eclipse 3.4 under Mac OS X, where Eclipse sets the file flags to read only and the .svn directories cannot be removed. For details see: Problems deleting .svn directories

The workaround is to start up a Terminal, cd to the workspace directory and run a command:

If you don't run chflags, then the setup of the features will fail under Mac OS X with a message about not being able to delete the .svn directories.

Import the features

in progress

1. In Eclipse: Window -> Open Perspective -> Java Browsing
2. Right click in the Package Explorer pane and select Import
3. In the Select window, expand Plug-in Development -> Features, hit Next.
4. In the Import Features window:
   1. In "Import From", uncheck "Choose from features in the target platform"
   2. In "Import From", change Plug-in Location to the location where triq was checked out:
      1. Under Windows, browse to c:/Documents and Settings/yourlogin/workspace/triq
      2. Under Mac OS X, browse to /Users/yourlogin/Documents/workspace/triq
   3. Hit Reload, then
5. In the Selection window, select Add-all and then Finish

Start up Ptiny

1. In the Package Explorer, open the ptolemy.ptiny project, Run -> Run Configuration
2. Create a Java Application called ExampleSystem, where the main class is ptolemy.kore.test.ExampleSystem
3. Run the ExampleSystem application, the results will appear in the console in Eclipse.

Note that we use a feature here to manage dependencies, but an alternative would be to add all the plugins to the classpath of the run configuration in Eclipse.

Adding a plugin

1. Go to the Java perspective
2. See the Eclipse Style Guide for details
3. File -> New -> Project -> Plug-in development -> Plug-in Project
4. Project name: ptolemy.domains.sr.examples, then Next
5. Plug-in Content Window:
   1. Plug-in Name: SR Domain Examples
   2. Plug-in Provider: Ptolemy Project
   3. Create an RCP (FiXME: text)
6. Templates Window: Select Hello RCP
7. The plugin perspective comes up
8. Go to MANIFEST, select ptolemy.Kore, save the manifest
   1. One idea is to add all plugins and then later remove unused dependencies
9. Create the java fle
10. Right click on plugin.xml, try running as an example
11. Run Configurations -> Plug-ins -> Add Required Plugins - The number of plug-in is displayed.

Adding a plugin to the SVN Repository

1. In the Package Explorer, right click on the plugin and select Team -> Share Project
2. In the Share Project window, select SVN
3. In the Share Project with SVN Repository window, select the appropriate existing repository, in our case svn+ssh//source.eecs.berkeley.edu/chess/triq
4. Important: add the project to the trunk. In the Enter Folder Name window, click on Use specified folder name, then select trunk and then type in the plugin name.

Attach:Ptolemy/eclipseShareProjectEnterFolderName.gif Δ Screenshot of Eclipse Enter Folder Name Window. Note that trunk and the plugin name is selected

1. For each package, decided what to add
   1. We usually don't include these files: *.class, makefile, .svn/,

Naming Conventions

• Eclipse Naming conventions (e.g. for plugins): http://wiki.eclipse.org/index.php/Naming_Conventions
• Should we rename all the packages to org.ptolemy? This would require touching basically every file. The MoML Filter could help some. We would also need to change the tests

Rules

Below are some rules for triq

• We should avoid including IDE specific features in the core and build system.
  • The MANIFEST.MF files should not include Eclipse- features
• We must be able to support a headless nightly build
• We must be able to support multiple IDEs:
  • Eclipse
  • Command Line
  • Netbeans
• Development of the makefiles will cease
• We should avoid replicating text in ant and other files
• Where we can, we should support autogenerating files

Package Dependencies

Ptolemy Package Dependencies on the Kepler-dev site.

Determining Which Ptolemy II Packages are Necessary

I used this command to determine which Ptolemy II packages are necessary:

To run the SR TokenRing demo in Vergil, these packages are necessary

If we run with -ptiny, then only these domains are required:

However, why are ct and erg required?

Build

There are some special projects configuring the build:

ptolemy.feature

a feature groups up plugins that belong together. So for testing here's only the Kore plugin in it for now. Later you might have different features (and even composite features) for different "distributions" of ptolemy.

ptolemy.updatesite

This includes only one configuration file "site.xml", specifying which features should be available for installation from the update site. To actually build everything else necessary for the site, right-click the site.xml, PDE-Tools -> Build Site. Everything needed for the site will be generated.

ptolemy.build

Includes the tricky part which is the headless build setup config files. These were created manually. Most important are

• build.properties: Sets some target specific properties. See eclipse PDE help for more details. Especially for RCP applications this might get quite complex.
• build-ptolemy.xml The manually created outter build file. It's a simple ant file, though it could be simply replaced by a different system, e.g. integrated into the make process.

GUI Build using Eclipse

1. Open ptolemy.updatesite project
2. Right-click on site.xml -> PDE Tools -> Build Site
3. That's it!

Headless Build

1. Checkout the ptolemy.build project
2. Edit the build-ptolemy.xml file to your setting, i.e. set properties of your eclipse installation and svn.
3. Call ant: ant -f build-ptolemy.xml all
4. The whole triq repository will be checked out to ptolemy.build/build
5. ant will call the Eclipse AntRunner to do the main build process (there are special ant targets for building features included in Eclipse)
6. eventually ptolemy.build/build/ptolemy.updatesite will contain the required jars of all plugins that can be installed

• Build and Test Automation for plug-ins and features - 2005, for Eclipse 3.0
• Ganymede Builder Configuration Properties

Problems

Running ant from the command line fails:

Solution: "To start up a headless Eclipse instance which then executes an Ant build file, Eclipse must be started as AntRunner application. " Under Windows:

However, this is slightly out of date. Hauke provided a better version of the command in ptolemy.build/build-ptolemy.xml. Below is a shell script:

Problem: antrunner fails to define eclipseBaseURL

Eclipse Ganymede Builder Configuration Properties says:

I tried setting eclipseBaseURL in antrunner:

but the code in customTargets.xml expects a .zip file, not a MacOS .tar.gz file. The solution is to pass -DskipBase=true to java call.

This message can also occur if build.properties cannot be found.

Problem: Unable to find feature

Solution: It turns out that ptolemy.ptiny/feature.xml did not exist.

Problem: lots of warnings

Solution JDT Plug-in Developer Guide > Programmer's Guide > JDT Core has JDT compiler arguments. The solution is to add the following to ptolemy.build/build.properties

Problem: compilation fails because of colt

When I run ant -f build-ptolemy.xml compile, I get

Looking at ptolemy.codegen/build.xml, I see that only ptcolt.jar is included in the path, and not the actors:

The ptolemy.actor.lib.colt MANIFEST.MF file looks ok though.

Q: How is ptolemy.codegen/build.xml created?

A: /Applications/eclipse/plugins/org.eclipse.pde.build_3.4.1.R34x_v20080805/scripts/genericTargets.xml has a generateScript target that invokes eclipse.buildScript

Here's another data point: In Eclipse, right clicking on ptolemy.codegen/build.properties and selecting PDE Tools -> Save Ant Build File yields an ant file that has the same problem. However, in Eclipse, building seems to work just fine? The ant file that is generated looks like the ant fragment above.

Solution: Removing Bundle-ClassPath: ptcolt.jar from ptolemy.actor.lib.colt/META-INF/MANIFEST.MF seemed to do the trick.

Plugin Installation

1. In a (fresh) Eclipse open help -> Software updates..
2. Switch to Available Software tab and select Add Site
3. Add either local site pointing to your ptolemy.updatesite dir or set URL of location where the ptolemy.updatesite is served by a webserver
4. Install the feature and restart Eclipse
5. To check if it is set up correctly: open Plug-In view from PDE view category. The prolemy plugins should be visible

Classpath Issues

See OSGiAndMoMLParser

Getting started issues

The problem is that each bundle is a project and each bundle is in triq/plugins.

Goals

1. It should be very easy for new users to check out the Ptolemy II development environment, which will include all the bundles that are under development
2. Users should get new bundles when they update
3. Old, obsolete bundles should be removed.

One way is to check out triq and then import the plugins.

Import->General->Existing Projects into Workspace

Hauke suggested using Import -> General -> Existing Projects into Workspace. The problem here is if I change Select Root Directory to /Users/cxh/Documents/workspace3/triq/plugins, hit Refresh, then Finish, I get a message Path for project must have only one segment.

Re: Path for project must have only one segment. says that projects of projects are not supported. Perhaps we need to look into working sets?

Are there other ways to get started?

Notes about setting up Team Project Sets (psf files)

1. Create a new project in triq called project-sets
2. Select all the plugins
3. Right click and select Export -> Team -> Project Sets
4. In Export a Team Project Set, review the packages, click next
5. In Export a Team Project Set, Select the export destination, in Workspace browse to the project-sets project (created above).
6. Create a file called ptiny.psf, then click finish. If you are prompted to overwrite, do so.
7. Check in the new project with Team->Share Project

Todo

• Should we refactor from ptolemy to org.ptolemy
  • We could use the MoMLFilter for backward compatibility
  • We should run scripts to update the .xml files so that the user is not prompted to save
  • The tests will need to be updated, which is a bear
• Should MoMLSimpleApplication be moved to ptolemy.moml.examples? See the naming conventions for details. I moved MoMLSimpleApplication to ptolemy.moml.
• actor.lib.image has some gui actors that should move to actor.lib.gui so that we can possibly support processing

images in a non-graphical environment

• The problem here is that actor/lib/image/image.xml refers to both gui and non-gui actors. Does this matter?

• Set up website for ptolemy.feature
• Is there a way to update all of the build.properties files by having them refer to one file? The alternative is to open each file. Not sure about this, but build.properties is part of Rich Client Platform.
• We should look into fragment to see if they can handle configuration issues like optional packages not being present. Fragments are used to override classes on for platform dependent basis.
• What about plug-in naming conventions?
  • Should we use names for groups of packages like ActorKore? Should these names have initial capitalization? Really, these would be features. I set up a couple at the bottom of $PTII/mk/jnlp.mk, which I could checkin. We should probably have a feature per binary and configuration (vergil, vergil -ptiny, viptos, ptolemy etc.)
• Possibly delete the .cvsignore files? Make sure that the ignore properties are set on the directories, see Ignore Patterns for CVS Users
• Being able to use Vergil Graph Editor in Eclipse, the problem is what happens when we look inside or when we plot data?
  • Right now, where the plotters appear is encoded in the model. This would be a problem in Eclipse views.
• Looks team project files
• Better extension points such as separating interface and implementation. Using abstract classes might help because changing an abstract class does not require implementors to update their implementations.