This document describes how to develop code to run in the SLAC eclipse applications lab (hereafter named "Seal") environment. Because Seal is a customized eclipse environment, many of the platform-specific development details are covered in eclipse development books. The point of this document is to inform developers about our local customizations and conventions, as well as to provide a quick start guide of sorts.

Running the IDE

You can develop for Seal using any particular instance of eclipse 3.3, as long as you have access to the filesystem on which the target platform is installed.

Setting up CVS

Once you've got your IDE running, you'll need to do a one-time setup of CVS. Open the "CVS Repository Exploring" perspective (select Window -> Open Perspective -> CVS Repository Exploring).

Right-click in the "CVS Repositories" view at the left, and select New -> Repository Location.

Supply the following values:Host: localhost
Repository path: /afs/slac/g/lcls/cvs
User: your AFS user name
Password: leave blank
Connection type: extssh
Leave the "Use default port" option selected. Ideally, you should not select "Save password", though in reality it's necessary since eclipse won't always prompt for a password when doing CVS operations.

Note that using "localhost" for your the server assumes that your machine has AFS access. If not, use the name of any ssh-accessible server that does have AFS access.

After clicking "Finish", you should see the newly added CVS location in the repository explorer.

You can explore the Seal repository by expanding HEAD -> physics -> seal.

Setting the target platform

In order to make sure that you are developing and testing against the seal platform, you need to set the plug-in development target in the eclipse preferences. To do so:

  1. Make sure that you have checked out target.seal from CVS into your workspace: in the CVS Repositories view, right click on target.seal, and select "Check out" from the popup menu.
  2. Next, select Window -> Preferences -> Plug-in Development -> Target Platform.
  3. At the bottom of the preferences page, in the "Pre-defined Targets" group, select "Browse".
  4. In the pop-up box, expand "target.seal", select "seal-current.target", and click "Ok".
  5. Next click "Load Target", next to the browse button
  6. Finally, click "Ok" to save the settings ans dismiss the preferences dialog.

After having done this, the java compiler will look in the target platform and in the current workspace for classes to satisfy code dependencies in the workspace. Also, when it comes time to test, you will be able to run your code using the production Seal plug-ins without having to deploy.

Project Organization

We've adopted the convention for Seal that every eclipse project corresponds to a cvs module under physics/seal . This means that you can checkout the entire seal code base by expanding {{physics/seal }}in the CVS Repositories view, selecting all of the modules, right-clicking to get the context menu, and selecting "Check out".

Notice that the projects seem to have a peculiar variety of names. There is an underlying madness to the naming method.

As you may now, the java convention for naming classes is to enclose them within namespace packages that are as unique as possible. The common technique is to prepend some portion of your organization's internet DNS name to create this scope. So for example, a package that you might be inclined to name cmlogviewer should more properly be named edu.stanford.slac.cmlogviewer. The convention for eclipse plug-ins follows similar scoping convention, though the name of the plug-in need not necessarily reflect the names of contained classes.

However, it can get obnoxious having to mentally discard the edu.stanford.slac.}}component of so many projects, so we've decided not to fully qualify the names of projects that we develop locally. Instead of {{edu.stanfod.slac.cmlogviewerwe simply name the project directory cmlogviewer. Note, however, that the resulting plug-in should still use the fully qualified name --this pertains only to project directory names.

For projects not developed at SLAC, we retain the fully qualified name, e.g. gov.sns.xal.

Glancing through the list of Seal projects in CVS, you'll notice that some have simple names and others have simple names appended to a prefix like target, update, or feature. The specially named projects are eclipse projects of the corresponding type. The target.seal project contains definitions of the seal target (to be expounded later). The update.seal project defines the eclipse update site that we use to deploy newer versions of plug-ins to the seal client. The feature projects define the eclipse "features" that encapsulate certain bits of Seal functionality, as defined in contained plug-ins.

Plug-ins

Creating a plug-in project

You can create a new plug-in project using the "New Project" wizard (accessible via File -> New -> Project -> Plug-in Development -> Plug-in Project). Be sure to name the project in accordance with the conventions outlined above. The wizard will ask for the project name. This might be something like "correlationplot". After supplying the name, you can accept all of the defaults in the initial wizard page. When you click "Next", however, you'll need to change the "Plug-in ID" field to "edu.stanford.slac.correlationplot", for example. Other than that, you can accept all other defaults.

If you click "Next" rather than "Finish" from the second page, you'll have the option of creating your new project from a template. Depending on your goals, you may find the "Plug-in with a view" or the "Custom plug-in wizard" to be helpful.

Developing a plug-in project

At this point, you should consult an eclipse plug-in development book for details about developing plug-ins. Also consult the following projects for more information about Seal-specific APIs and available facilities:seal.coreContains definitions useful / necessary for all Seal plug-ins. Presently, it contains nothing more than the definition of a View category to be used by Seal views.pal.coreSimilar to seal.core, but providing definitions for physics appsseal.utilGeneral purpose locally developed utilty code of potential use to all Seal appsexternalContains all third-party code of use to Seal and Pal apps, for which it doesn't seem appropriate to create individual plug-ins.

Testing a plug-in project

Once you've got your code built, you will of course want to run it, possibly under a debugger. There are several ways to run your plug-in; here's one that leaves the least to eclipse's default behavior:

  1. Right click your project in the eclipse package explorer, and select Run As -> Run...
  2. In the popup dialog box, highlight "Eclipse Application", and press the "New" button above the list (it's the icon that looks like a blank page with a plus mark).

Having done this, you will now have a default-configured run specification. You may want to rename it from "New_configuration" to something more descriptive, like "MySeal", in the "Name:" text box. Now notice the tabs under the Name field. These give you the opportunity to control many aspects of how eclipse will run your code. You may not need to modify much of this, but it's good to familiarize yourself with the controls that are available.

Under the "Main" tab, within the "Program to Run" group, select "Run an application", and make sure that "org.eclipse.ui.ide.workbench" is selected.

Most crucially, under the "Plug-ins" tab, select "Choose plug-ins and fragments to launch from the list". Verify that both "Workspace Plug-ins" and "Target Platform" are selected, and that any plug-ins you want to run from the workspace which are also available in the target platform have their checkboxes selected appropriately (if both are selected, the one from the workspace should override the one from the target definition).

Having now set up your runtime configurtation, you can run it via the Run menu or by selecting the run button on the toolbar. If you do this, eclipse will startup running the production Seal plug-ins, in addition to, or overridden by those in your workspace.

Debugging a plug-in project

To debug a plug-in, follow the steps for testing, above, but instead "running" the specification you defined, "debug" it instead. You can do this via the Run menu or via the debug icon in the toolbar.

Consult an eclipse tutorial for information about using the debugger.

Committing a project to CVS

Before committing your project to CVS, verify that it builds cleanly, without errors or meaningful warnings .

First-time import

When you create a new project, you need to add it to the CVS repository. To do so,

  1. Right click the project in the eclipse navigator, and select Team -> Share Project
  2. In the popup dialog box, select the existing repository location that was previously setup as described above, and select "Next"
  3. Select "Use specified module name" and type the CVS relative path of your project. For "correlationplot", this would be "physics/seal/correlationplot" (We can't just use the default "Use project name as module name", because that would place the project in the top level of the CVS directory, which is not what we want).
  4. Click "Next", and look at the things to be committed. If you see something that does not belong under version control, right click it in the list, and select "Add to .cvsignore" in the popup menu.
  5. Click "Finish", and the commit wizard will start. You should enter a useful comment here. For a newly created project "Initial import" is probably good. Be sure to check the list below the comment box for any elements to add to .cvsignore. Sometimes the list at commit time differs from the list that you saw previously when initally adding the project. For example, the "bin" directory usually shows up. That's a good one not to commit since it contains the compiled classes.

Committing changes to the repository

After adding new files or modifying pre-existing ones, you can commit your changes to CVS by selecting those resources you wish to commit from one of eclipse's resource, navigation, or pakage exploring views, then clicking the right mouse button to bring up the context menu, and selecting Team -> Commit.

This will bring up the commit wizard. Enter a meaningful comment in the text box, and verify that everything you wanted to add is included in the transaction. Also make sure to avoid adding anything you don't want to commit by right-clicking on the resource in the commit wizard and selecting "Add to .cvsignore" from the popup menu. Note that the commit wizard will attempt to add any new files it finds within the directories that you selected to commit, so it's always a good idea to double-check that nothing is being added to version control that you don't actually want.

Features

While all functionality of Seal (indeed any eclipse application) is provided by plug-ins, usually any one plug-in will require that other plug-ins also be installed in order to work. This is why eclipse "features" exist. A feature groups together plug-ins and features into a deployable unit.

While we have no well-defined rule for what a feature should encompass, it's a good idea to consolidate into a feature functionality that one might wish to install or upgrade independent of other such functionality. For example, the feature feature.cmlogviewercontains the org.jlab.cmlog and cmlogviewer plug-ins. It provides the cmlog browser functionality, which is useful in and of itself.

Note that multiple features can include the same plug-ins. As long as the versions are compatible, this causes no ill-efects, since the eclipse feature management code doesn't install redundant plug-ins.

Creating a feature project

You can create a feature project much as you would create a plug-in.

  1. Select New -> Project -> Plug-in Development -> Feature Project.
  2. Name your project "feature.something", where "something" usefully designates the funtionality consolidated in yout feature, e.g. "feature.correlationplot".
  3. Change the Feature ID to comply with our conventions, for example "edu.stanford.slac.correlationplot"
  4. Select "Finish", and navigate to the feature project's feature.xml file
  5. Opening this file in the editor, select the "Plug-ins" and or "Included Features" tabs to add plug-ins and features that this feature should bundle up.
  6. select the "Dependencies" tab and click "Compute" to enumerate dependencies. Also check "Recompute when feature plug-ins change".
  7. Consult an eclipse reference for more involved details about defining features.

Be sure, in the overview tab of features.xml, to specify the following field values:Update Site URL: file:/afs/slac/g/lcls/physics/seal/update-site
Update Site Name: Seal Updates

This allows the eclipse update manager to scan for updates to the feature via the official update site.

Deploying

NB Deploying a project for Seal is complicated by several factors that we hope to ameliorate in the near future. At present, it's best to avoid releasing too frequently.

Overview

The process to deploy newly developed or modified code for Seal production use consists of the following steps:

  1. After testing the pertinent plug-ins, bump the version numbers appropriately and commit to CVS.
  2. Create or update the pertient features, bump the version numbers appropriately, and commit to CVS.
  3. Update the special feature feature.seal.release, bump the version number and commit to CVS.
  4. Build the Seal product in feature.seal.application.
  5. Copy the built product to the install area, and update the symlink.

The Release Feature

Seal comprises many individual features, but one special feature consolidates them all into one release. We use feature.seal to initialize and update the official production of Seal. The point is to simplify updating, and to facilitate future automation of the deployment process.

Obviously, it's critical to update this feature to include newly developed features in order to get them into production.

Building the Seal Application Product

  1. Open seal.product from the feature.seal.application project.
  2. On the "Overview" tab, in the "Exporting" section, click the "Eclipse Product export wizard" link.
  3. In the pop-up a dialog box, in the "Root directory" text box, type a string designating the version of the released application, for example "0.2". In the "Directory" text box, enter /afs/slac/g/lcls/physics/seal/product.
  4. Leave every other option at default setting and click "Finish".

When the build process completes, you'll get a message that there were some errors. Just dismiss the dialog box, and think to yourself "so what?". The final step to make the newly deployed product the current version is to update the "current" symlink in the same directory, and to run the rsync script to mirror the changes out to the production box.

Where's the hack

In CVS physics/seal/application/edu.stanford.slac.eclipse.ide.application. This is built by the feature.seal.application as described above.

  • IDEApplicatinProxy is the entry point.
  • The menu bar (to add Applications and Utilities) is overridden by IDEWorkbenchWindowAdvisorProxy.java.
  • To push CSS menu items down into Advanced, we added SEALMenuManager extending MenuManager. This creates the Advanced submenu and sets up the list of menus allowed to be at the top. The basic idea is that all menu items (from CSS) that want to contribute to the top level menu, are 'allowed' to do so, but they're set to "hidden". This is so that all plugins that expect to find CSS things do in fact find them. Then, those CSS items are added to the Advanced CSS menu, in which place they're set to "not hidden".
  • No labels