eclipse and me

OSGi Tracing in Equinox

2011-12-26T14:00:00.001+05:30

The Equinox implementation of OSGi provides the tracing APIs in org.eclipse.osgi plug-in since Eclipse 3.5. The tracing options are generally Boolean flags stored in a .options file as key-value pair. A typical .options file would look like this

org.my.plugin/ui=true
org.my.plugin/ui/editor=true
org.my.plugin/ui/prefs=true
org.my.plugin/debug=false
org.my.plugin/debug/data=true

The hierarchy is defined using the slashes. But this is only a general practice. The tracing does not understand this.

-osgi.debug
To load the values from the .options file, provide the file name as command line parameter (or program parameter in launch config)

command line arg example
eclipse.exe -debug C:\tracing\.options

program argument (in launch config) example
-Dosgi.debug=C:\tracing\.options

Using -debug is same as setting the osgi.debug system property.

Accessing the option values at runtime
1. In RCP application
If the RCP application has access to the org.eclipse.core,runtime.Platform object and thus they can access it directly like this

String value = Platform.getDebugOption("org.my.plugin/ui");

User can validate if the program is running in debug mode using Platform.inDebugMode() API.

2. In pure OSGi application
An OSGi application can access these options using the DebugOptions service

ServiceTracker debugTracker = new ServiceTracker(bundleContext, DebugOptions.class.getName(), null);
debugTracker.open();
DebugOptions debugOptions = (DebugOptions) debugTracker.getService()
boolean uiOption = debugOptions.getBooleanOption("org.my.plugin/ui", false);

Using the API has the advantage that user does not have to check for nullness.

More Tracing API
org.eclipse.osgi provides more APIs which are very helpful in logging the trace.

1. Registering a debug option listener
The listener can be registered as service using the BundleContext (that you receive in the activator class when the bundle is started)

final Hashtable<String, String> properties = new Hashtable<String, String>(4);
properties.put(DebugOptions.LISTENER_SYMBOLICNAME, TracingConstants.BUNDLE_ID);
bundleContext.registerService(DebugOptionsListener.class.getName(), new MyDebugOptionsListener(), properties );

2. Listening to the debug option change events
Once the listener is registered, a callback will happen each time a debug option is changed. The callback does not tells you the delta and instead throws the whole lot. So we can use this place to read and init from the DebugOptions

/* (non-Javadoc)
* @see org.eclipse.osgi.service.debug.DebugOptionsListener#optionsChanged(org.eclipse.osgi.service.debug.DebugOptions)
*/
public void optionsChanged(final DebugOptions options) {
//DebugTrace trace;
trace = options.newDebugTrace("org.my.plugin");
// boolean field
DEBUG = options.getBooleanOption("org.my.plugin/debug", false);
}

this is just an indicative code. You don't have to necessarily do it this way.

3. Writing to trace
This is the easiest part. Afterall the reason we did the whole exercise was to make the tracing simple. A handle to trace object can be obtained from the debug options.

/** Trace object for this bundle */
private final static DebugTrace TRACE = MyPluginActivator.getDefault().getTrace(); // returns the trace object obtained using options.newDebugTrace("org.my.plugin");

@Override
protected Control createContents(final Composite parent) {
if (MyPluginActivator.DEBUG) {
TRACE.traceEntry("/debug", parent);
}
...
...
}

Checking MyPluginActivator.DEBUG is optional. TRACE.traceEntry will check for the flag "/debug" anyway. This is to improve of the performance. We store the the flag values to boolean fields and update them through the listener.

4. Where is the log file?
The log is stored in the file as set in the debug options. By default, it tends to store them to workspace\.metadata\trace.log

options.setFile(new File("/path/to/trace/file"));

5. Controlling the trace logs
The logs are conntolled by two system properties

eclipse.trace.size.max : The system property used to specify size a trace file can grow before it is rotated
eclipse.trace.backup.max : The system property used to specify the maximum number of backup trace files to use

Easier way to manager the logs?
PDE will be providing UI for managing the logs and make them dynamic. See Bug 296631. This is mostly like to make it to Juno M5 release.

What do you mean by dynamic?
If you notice, the debug options can be loaded at the launch time (using -osgi.debug) or programatically when running. However, if you wish to turn the tracing on/off in a running product, its tricky. PDE will be providing an extension using which a plug-in can expose its debug option flags. The UI will display these flags in preferences where they can be turned on/off for a running application. Cool! isn't it?

* If you find any discrepancies in the above post, please bring it to my notice so that they can be updated.

Update: Tracing UI is now available in latest Integration builds and will be there from Juno M5.

PDE Good Practices: #8 Set correct EE and Java compliance levels

2011-07-24T14:15:00.002+05:30

The Execution Environment that is set on the plug-in manifest governs the lowest JRE version the plug-in can work with. If the OSGi runtime (equinox) is running with a lower JRE than the plug-in will not be loaded.

So marked the EE carefully to the lowest JRE you wish to support.

Similarly, ensure the Java compliance level matches the EE.

For example, assume the EE is set to J2SE-1.4 and the Java compliance to 1.5. Now, if you use annotations, the code would still compile in your workspace. However, when deploying, the plug-in would fail it will tell OSGi that it can run with 1.4 but actually it can not.

Extension Point Schema Builder

2011-07-23T16:32:00.002+05:30

The name says it all. This builder is responsible for compiling the extension point schema files. But they are exsd (xml format) files. What would one compile them in to. HTML of course :)

So the name does not really says it all. Before we proceed, we need to see the Schema compiler preferences.

This page gives the the preference to generate the documentation for the extension point schema. When checked, a reference document is generated for each schema. The document (in HTML format) is generated in the folder name as provided in the preference page. As you can see, the default value is 'doc'. The extension point schema builder is responsible for creating this document. If the check-box is not checked, then this builder will not do anything.

Plug-in Manifest Builder

2011-07-22T16:30:00.002+05:30

Plug-in Manifest Builder or in short, manifest builder is contributed by PDE through org.eclipse.pde.core plug-in. This is the builder that would compile your plug-in each you change plug-in dependencies, modify build.properties, change classpath, add or remove libraries, save your code/classes. It compiles the plug-in and validate that required files (plugin.xml, etc) are in place and in correct shape.

You may have a look at org.eclipse.pde.internal.core.builders.ManifestConsistencyChecker for the exact details.

It is one of the two builder that any plug-in/fragment or equinox bundle project will have by default. It is a bit paranoid builder. If it can not understand any change (resource delta) it will go for full build of the project.

The Plug-in Manifest Compiler preference page has a bunch of options that control the problem severity generated by the builder.

Using SWTBot as script while developing RCP app

2011-06-12T11:18:00.000+05:30

SWTBot is a great tool for writing UI tests. However, you can also use it as script to automate your clicks while developing UI.

Use Case

Suppose we are developing a wizard and we are designing the UI on third page. Now each time we will have to launch our application and then invoke the wizard. Provide template info for first two pages to reach the page where we are actually working currently. While designing UI we do these steps a number of times.

You can use SWTBot to automate these clicks. The idea is simple. Write an SWTBot script for the clicks to be automated, invoke it using Startup extension.

How to do it?

1. Add SWTBot to Target Platform
i) Edit the target platform and add a new 'Software Site' location.
ii) Provide the URL http://download.eclipse.org/technology/swtbot/helios/dev-build/update-site (see http://www.eclipse.org/swtbot/downloads.php for relevant url for your Eclipse version).
iii) Select 'SWTBot Eclipse features'.

2) Add the SWTBot script using Startup extension
i) Create a dummy plug-in.
ii) Add the 'org.eclipse.ui.startup' extension and create the class that will get invoked by it
iii) Add your SWTBot script to this class created above.
iv) You will have to add the dependency to 'org.eclipse.swtbot.eclipse.finder' for the SWTBot to compile.
v) Include this plug-in and the SWTBot plug-ins from the target to your launch configuration.

How this works?

The 'startup' extension makes the SWTBot script run when your application is launched. Adding the SWTBot to launch configuration will ensure it will be able to run when launched.

Eclipse Day India 2011

2011-04-19T11:11:00.000+05:30

Eclipse Day India 2011 will be hosted in Bangalore on Friday, May 6, 2011. The registrations are now open. Pick up your free ticket from http://eclipsedayindia.eventbrite.com/

Eclipse Day India is a non-profit annual event organized by Eclipse enthusiasts. It is one day event with talks about Eclipse. This year's edition will have two tracks which will consists of workshops, tutorials and technical talks. A tentative agenda is available at http://www.eclipseday.in/p/schedule.html

Thank you SAP Labs for hosting the event and Progress Software for co-sponsoring.

See you at Eclipse Day!

Self help with API Tooling Reports (Part II): Generating the API Use report using Ant Task

2011-02-04T22:40:00.000+05:30

The API Use report can also be generated using Ant tasks. See Eclipse help documentation for it here. If you already know how to run ant tasks in Eclipse, skip the rest of it.

1. Writing Ant script
I assume you know a bit of Ant already. If not, stop and step over to Ant Tutorial.
Create a new File and lets call it GenerateApiUseReport.xml. It will open in default text editor. Close it and Open it with Ant Editor (use right click on file and select 'Open With' -> 'Other...')
Now write this in the file.

The parameters match to the UI we discussed before.
Ant Parameters UI
location <=> Analyze
scopepattern <=> Bundles matching
referencepattern <=> References to
report <=> Report Output Location
considerinternal <=> Internal references
considerapi <=> API references
considerillegaluse <=> Illegal API Use

These two are not in UI
archivepatterns - Its exclude filter. It will be a comma-separated list with the format <bundle-id>:<relative-path-to-jar>

debug - Supplying a "true" will make the apitooling.apiuse ant task give out all the debug trace information. This might be helpful if for some reason the results are not expected and you need to investigate. Since default value is false, I would recommend leaving it out until you need it and know what you are doing.

2. Running the script
This is simple. You have to create a new Ant Build launch config from the External Tools Configuration wizard. But why do it when there is a shortcut. Just right-click in the ant editor and select 'Run As' -> '2. ant Build...'. This will automatically create an Ant Build launch config for you and open it. It will look like this

Hit the Run to execute the script. You can open this again from External Tools configuration wizard.

3. Generating HTML reports
The apitooling.apiuse ant task only generating the XML report. For generating the HTML reports we need to invoke the apitooling.apiuse_reportconversion task. The parameters are very simple. See the documentation here.

Since we would want to do this along with the report generation only. We can add this to same Ant script and
make it look like this

Self help with API Tooling Reports (Part I): Generating the API Use report

2011-02-03T23:19:00.000+05:30

API Tools is part of Plug-in Development Environment. It provides tooling support for tracking and managing your APIs and dependencies and can generate various reports. The Eclipse help discusses here about how to set it up.

What we will discuss here is how to generate various reports and making sense out of them.

Generating the API Use report

API Use report is the simplest of the report. It tells what APIs are referenced (used) by a given profile. A profile can be an API Baseline, a Target Definition or a directory containing an Eclipse product or just some plug-ins.

PDE provides an External Tools configuration wizard to run this report. The wizards can be launched from the Run menu -> External Tools -> External Tools Configurations...

This will open the External Tools Configurations wizard. Select 'API Use Report' from the left pane and press the 'New' launch configuration button.

The snapshot below shows the settings for an RCP product.

Analyze

You can choose an API Baseline, a Target Definition or a directory to run the report on. The report is a set of XML files. To make it human readable, there is an option to generate HTML report out of any existing API Use report.

Search For

Here you control what to look out for. The 'References to' takes a regular expression which will be used to match the APIs source. In this example the report will lookout only for the API originating out of bundles whose name starts with 'org.eclipse.'

API references: The APIs used in your product

Internal references: Marks the non-API - one coming from internal packages.

Illegal API Use: Usage that breaks the restrictions marked using JavaDoc tags.

Search In

This controls the search scope. The APIs references will be searched only in the plug-ins that match the regex provided here,

Reporting

This is self explanatory. The report will be churned out as a hierarchy of.folders and XMLs in the output location. And if checked for 'Create HTML reports', they will be generated too. The report is saved inside the folder 'XML' in the report output location. While the HTML reports are inside the folder named 'HTML'.

Self help with API Tooling Reports (Part III): Understanding the API Use Report

2011-02-02T11:09:00.093+05:30

API Tooling reports are collection of XML files. A typical API Use Scan report will look is like this

XML
│ meta.xml
│ not_searched.xml
│
├───plugin.a.b.c (1.0.0.201101280335)
│ └───com.example.myrcpproduct (1.0.0.201101280335)
│ ├───API
│ │ method_references.xml
│ │ type_references.xml
│ │
│ ├───ILLEGAL_API
│ │ type_references.xml
│ │
│ └───PRIVATE_PERMISSIBLE
│ method_references.xml
│ type_references.xml
│
├───plugin.x.y.x (1.3.0.v20100512)

│ └───com.example.myrcpproduct (1.0.0.201101280335)

│ ├───API

│ │ method_references.xml

│ │ type_references.xml

... ...

...

XML folder is where the report is generated

meta.xml contains the report parameters - the regex filters and locations, etc

not_searched.xml is the list of plug-in not looked into and why.

The XML folder will also contain a bunch of folders whose names are plug-in id (with version) whose API are referenced (used). These folders will again have sub-folder named as the plug-id id (with version) which references those APIs. The usage (or violation) is stored is XML files under their respective folders.

This structure is very technical and for sparing you the trouble of understanding it, the report can be converted to HTML files. So it will be more useful to understand them.

Example API Use HTML report

The report has three sections

Scan Details will show the parameters used for generating the report. This information comes from meta.xml mentioned above.

Additional Bundle Information gives the link to the bundles that were not searched. The color legends are self-explanatory

References section is a table detailing the bundles who are referenced (used) along with the number of references of different types. A reference is a usage of a type, method or field.

API - any public reference
Internal - any reference from an internal package
Internal-Permissible - any reference from an internal package but visible to the consuming (or referencing) bundle due to x-friends marking in manifest.
Fragment-Permissible - same as Internal-Permissible but from fragment bundles
Illegal - references which violates the API restrictions placed using JavaDoc tags.

Each bundle name is a hyper-link that would open the details for than bundle. The details for org.eclipse.apitest would look like this

Opening the details shows the list of the Referenced Types (types being used). Each type can be opened (follow the hyper-link) to see each member and visibility details.

This way you can find of each usage - valid or otherwise.

The other API Tooling reports too are structured in similar hierarchy. However, with API Use Scans you can do more ... so stay tuned for more.

Headless Build for Beginners - part V

2010-08-25T17:00:00.001+05:30

Headless building Update Site

There is no easy way to achieve this. There have been some discussions in past and the Build and Test Automation article too touched it in brief. But its all hacky. I tried various stuff but the closest I could get was build features and plug-ins using (mentioned in) a site.xml and generating the metadata for them. The site.xml can be placed with them manually but I could not find a way to (automatically) update the site.xml with the feature and plug-ins build qualifiers. (There are always hacks like having a dummy site.xml and do a find-replace in it. Or write a custom ant task that emits XML for ste.xml - none of the hack is very maintainable or scalable)

After more investigation I realized may be I was trying to solve the wrong problem. We really don't need the update site (not if you are using Eclipse 3.4 or later). A p2 repository is not only easy to generate but is also the recommended way of distributing features and plug-ins.

Headless building a p2 repository

Now a p2 repo can be generated either from a bunch of features and plug-ins or directly from a product configuration. Both explained in Eclipse help. We will here take a product configuration and build a p2 repository for it. The setup will be same as discussed before. However this time, we will copy all the files from /org.eclipse.pde.build/templates/headless-build folder to our build configuration folder (build\buildConfiguration). Thus, the build structure will now looks like this

<buildConfigurationDirectory>
       allElements.xml
       build.properties
       customAssembly.xml
       customTargets.xml
<buildDirectory>
       plugins/
              com.example.helloworld
              com.example.product
                     example.product
       features/
              com.example.helloworld.feature

The current setup will generate the product when build. We now need to add a hook for repository generation. This can be done in customAssembly.xml. Open it in Eclipse or your favorite text editor and make the following changes in post.gather.bin.parts target.

<target name="post.gather.bin.parts">
 <p2.publish.featuresAndBundles
  repository="file:/${buildDirectory}/repository"
  source="${buildDirectory}/tmp/${archivePrefix}" 
  compress="true"
 >
 </p2.publish.featuresAndBundles>
</target>

Note that p2.publish.featuresAndBundles is just of the of ant task that can be used to generate metadata. There are more for different situations. The idea here was more to see how to add custom call in ant scripts.

Run the build as before

java -jar c:\eclipse\plugins\org.eclipse.equinox.launcher_1.1.0.v20100507.jar -application org.eclipse.ant.core.antRunner -buildfile c:\eclipse\plugins\org.eclipse.pde.build_3.6.0.v20100603\scripts\productBuild\productBuild.xml -Dbuilder=c:\build\buildConfiguration

This will create a p2 metadata repository in file:/${buildDirectory}/repository folder. You can control the location using repository property.

Headless Build for Beginners - part IV

2010-08-24T17:00:00.002+05:30

Customizing the build

Not always we want the build to happen according to the out-of-the-box scripts.In fact, customizations are almost always needed - be it fetching the sources or the way we wish to assemble them. PDE Build provides a set of templates which can be used to hook in the customize (add to and/or override) the default behavior.

These templates are available in PDE Build plug-in (inside templates\headless-build folder of org.eclipse.pde.build_<version><qualifier>). The scripts and templates are one the main reason why PDE Build plug-in is a directory and not a jar.

The purpose and usage of these templates have been explained nicely in Eclipse help under the topic Customizing a Headless Build.

These templates are

customTargets,xml
allElements.xml
customAssembly.xml

In short, the customTargets.xml have various pre- and post- ant targets that build.xml (or productBuild.xml - in case you are building a product) calls before and after each process (like setup, source fetch, build, assemble, package, etc). Similarly, the targets in allElements.xml and customAssembly.xml gets delegated for various jobs.

To use these templates we need to copy them in the build configuration directory (c:\build\buildConfiguration in our example) where we stored build.properties file in previous steps. And then modify the appropriate targets. This is what we will do for building an update site in next step.

e4 Talk by Boris

2010-08-17T15:11:00.001+05:30

Boris Bokowski (@bokowski) will be talking about e4 at IBM EGL Campus on Friday, August 20, 2010 (3 to 4 PM). See the details on the Bangalore Eclipse Developer's Groups.

PDE Good Practices: #7 Keep build.properties synced

2010-07-30T00:28:00.000+05:30

We often land up in situations like "it was working in my workspace but exported plugins are behaving differently". An important thing to notice is that workspace is build considering the project classpath settings. However, the Export wizard or headless build does not have access to it. They reply on build.properties file. Thus it is very important to keep it in sync with the project settings. Eclipse Helios (3.6) added a bunch of preferences to help you do just that.

I would even recommend having project specific preferences enabled whenever possible. This will ensure all developers are reported for problems and their workspace settings doesn't have them ignored.

PDE Good Practices: #6 Share target definitions

2010-07-30T00:18:00.000+05:30

Always have your target definitions in a project instead. This way

it can be added to source control repository and changes to it can be tracked.
all the other members who wish to work with that code can share it and thus compile against the same target. This will keep everyone on same page.

PDE Good Practices: #5 Prefer target over workspace

2010-07-22T12:01:00.000+05:30

Remember it is a 'good practice' and not necessarily the best suited to your needs. So unless you are sure what you are doing, it is advisable to keep all the dependent plug-ins in target. Check-out only the those which you need to modify, The benefits are

A small workspace is easier to follow
Even a full build will be much faster
Since target platform can be shared, you can be sure that you are build against the same exact version as your peers
Launch will be faster

If you miss that Types are not showing up in the searches, use PDE preference to add all the target plug-ins to the Java search.

PDE Good Practices: #4 Use startup code carefully

2010-07-20T11:43:00.000+05:30

Be very careful when adding code to

Plug-in load and constructor

org.eclipse.ui.startup extension

These places have a big impact on application startup time. Also note that the if there are many plug-ins dependent on one plug-in and that plug-in is doing something on load (which it shouldn't be) then it may be delaying the loading of the whole stack.

Headless Build for Beginners - part III

2010-07-20T00:28:00.000+05:30

Automated building an RCP application from a product configuration file

Most of this post contains same info as the eclipse help page with same heading.

Creating a product configuration file is easy. Check the eclipse help page explains it well. Assuming the our product config example.product looks like this and resides in a plug-in com.example.product.

Basic Setup

We will need 3 directory paths

where the features and plug-ins to be build will reside. We will call it buildDirectory.
where the build configuration file (build.properties) will reside. We will call it buildConfiguration.
where the eclipse installation resides. We will call it baseLocation.

Now to prepare these directories

Copy the features and plug-ins in side the buildDirectory. Ideally this will be a source checked out from the version control system. Custom ant tasks can be used to automate that. For this example, the directory shall look like this

<buildDirectory>
       plugins/
              com.example.helloworld
              com.example.product
                     example.product
       features/
              com.example.helloworld.feature

Copy build.properties file from baseLocation/plugins/org.eclipse.pde.build_<version>/templates/headless-build to buildConfiguration folder. This file will configure the build and the output.
Now we need to edit this build.properties file and fill in the parameters

product=C:/build/buildDirectory/plugins/com.example.product/example.product

buildDirectory

baseLocation.

archivePrefix=HelloWorld
configs=win32, win32, x86

baseLocation

RCP Delta Pack

buildDirectory=C:/build/buildDirectory

buildDirectory

buildType=I
buildId=ExampleProductBuild
base=C:/
baseLocation=${base}/eclipse

Running and understanding output

The build will be invoked as before

java -jar <eclipse-installation-path>\plugins\org.eclipse.equinox.launcher_<version><qualifier>.jar -application org.eclipse.ant.core.antRunner -buildfile <eclipse-installation-path>\plugins\org.eclipse.pde.build_<version><qualifier>\scripts\productBuild\productBuild.xml -Dbuilder=c:\build\buildConfiguration

example

java -jar c:\eclipse\plugins\org.eclipse.equinox.launcher_1.1.0.v20100507.jar -application org.eclipse.ant.core.antRunner -buildfile c:\eclipse\plugins\org.eclipse.pde.build_3.6.0.v20100603\scripts\productBuild\productBuild.xml -Dbuilder=c:\build\buildConfiguration

The output will look like this

I.ExampleProductBuild
│ ExampleProductBuild-win32.win32.x86.zip
│
└───compilelogs
   └───plugins
   └───com.example.helloworld_1.0.0.201007191243
   @dot.log

The folder I.ExampleProductBuild will contain the build logs and the product build ExampleProductBuild-win32.win32.x86.zip. If we had chosen other configs they too will appear here in separate zip (or whichever format we specify).

PDE Good Practices: #3 Lazy-loading and Singleton plug-ins

2010-07-08T16:42:00.000+05:30

Lazy Loading

When a plug-in is marked for lazy loading it is NOT loaded until it is needed. This helps in keeping the memory footprint of application small as possible.

A plug-in can be marked for lazy loading by checking the 'Activate this plug-in when one of its classes is loaded' checkbox on the Manifest editor overview page. This create the following entry in the Manifest.MF file.

Bundle-ActivationPolicy: lazy

Singleton plug-ins

It is preferable to use singleton plug-ins unless you know what you are doing. If a plug-in exposes extension points then it has to be singleton. But if not, it is still advisable to keep them singleton. This would ensure only one version of the plug-in is loaded at a time and generally its the latest one (unless version bound).

A plug-in can be made singleton by checking the 'This plug-in is a singleton" checkbox on the manifest editor overview page.

OSGi environments generally prefer non-singleton plug-ins as they can be dynamically installed.

PDE Good Practices: #2 Externalize bundle strings

2010-07-01T23:04:00.000+05:30

Externalize all bundle strings.

Use ‘Usage of non-externalized strings’ preference

Enabling the preference marks all the strings that should be externalized.

Use 'Externalize Strings Wizard' to externalize the strings

'Bundle-Localization' entry in Manifest points to the properties file containing the externalized strings.

The value 'plugin' for 'Bundle-Localization' entry means that there will be a 'plugin.properties' file in the plugin root containing the externalized strings e.g. '%Bundle-Name'.

PDE Good Practices: #1 Separation of Concerns

2010-07-01T19:41:00.000+05:30

Do not create monolithic plug-ins.
A plug-in is used to group the code into a modular, extendable and sharable unit.
Prefer having separate plug-ins for Core, UI, Doc, etc
Separate the platform/locale code into fragments.
Put related plug-ins under same feature.

Headless Build for Beginners - part II

2010-06-16T01:08:00.000+05:30

Building through features

Plug-ins are rarely required to be build in isolation. The nicer way of building them is through features. Of course, features are more useful from distribution and deployment point of view. A feature is build the same way as a plug-in. Include the required plug-ins in the feature.xml and generate the build.xml from build.properties file (right-click and choose PDE Tools). Now launch the feature build.

java -jar <eclipse-installation-path>\plugins\org.eclipse.equinox.launcher_<version><qualifier>.jar -application org.eclipse.ant.core.antRunner -buildfile <eclipse-workspace-path>\<feature-project-path>\<build-xml-path>

example

java -jar C:\eclipse\plugins\org.eclipse.equinox.launcher_1.1.0.v20100507.jar -application org.eclipse.ant.core.antRunner -buildfile C:\workspace\com.example.helloworld.feature\build.xml

Note that build will fail if the included plug-ins do not have the build.xml generated for them. This is not a likely scenario and definitely not the way it is done. But let it be for time being. Generate the build.xml for all the plug-ins for build to succeed. Later on we will see how it can be done without it.

Passing parameters to AntRunner from command line

The build generated by the above command will leave the feature jar inside the feature project and the plug-in jar inside the plug-in project folder. Of course they shouldn't scattered all around. They need to be collected to one place.

Open the build.xml for the plug-in project and inside the 'init' target there is one property called 'plugin.destination'. It is this location where the jar is finally created by the 'build.update.jar' target.

<property name="plugin.destination" value="${basedir}"/>

Change the value of this property to "${buildDirectory}". Make the similar change for the 'feature.destination' property in the build.xml for the feature project.

If the build is triggered now, it will fail because it can not find the value for the 'buildDirectory'. The value can be provided through command line using -D option.

java -jar <eclipse-installation-path>\plugins\org.eclipse.equinox.launcher_<version><qualifier>.jar -application org.eclipse.ant.core.antRunner -buildfile <eclipse-workspace-path>\<feature-project-path>\<build-xml-path> -DbuildDirectory=<build-storage-location>

example

java -jar C:\eclipse\plugins\org.eclipse.equinox.launcher_1.1.0.v20100507.jar -application org.eclipse.ant.core.antRunner -buildfile C:\workspace\com.example.helloworld.feature\build.xml -DbuildDirectory=c:\build\buildOutput

When the build is run, ${buildDirectory} will be replaced by the value(location) provided and jars will get created there.

More parameters can be supplied using -D<variable-name>=<value> from the command line.

Ant properties file

Passing parameters from the command line is not very scalable or maintainable. A better way is to pass the parameters using a properties file.

Create a properties file, say, 'custom_build.properties' inside a folder, say, 'buildConfiguration'. The name 'custom_build.properties' have been chosen to distinguish it from 'build.properties'. Carefully note that though both are name=value kind properties file, it is common(rather better) practice to not mix them. Since 'build.properties' has a special meaning in context of PDE, it is recommended that a different name is used to avoid any confusion.

Store the property and its value in the properties file.

buildDirectory=c:/build/buildConfiguration

Note the forward slashes instead of backslash. The backslashes will work too but needs to be escaped.

Now open the build.xml for the feature project and add the 'loadproperties' entry under the 'project' tag.

<project name="com.example.helloworld.feature" default="build.update.jar" basedir=".">
 <loadproperties srcfile="../../buildConfiguration/build.properties" />
        ...

This entry needs to be made only in feature project's build.xml and is not required for the plug-in projects' build.xml. They still can use the same variable name and will get the value from the properties file.

Note that the value for the 'srcfile' is a relative path and the ../../ (grand-parent directory) indicates that the properties file has been kept in one folder outside the folder (or workspace) containing the projects.

Headless Build for Beginners - part I

2010-06-14T12:05:00.000+05:30

The easiest way to generate the plug-in jars is through Export Wizard. Assuming we already know this, lets try to play with headless build.

Headless Build

Here the workbench (IDE or UI) is referred to as 'head'. Headless build essentially means running the builds from command line in non-UI mode. This can be achieved by various means, however, we will start with java command line and org.eclipse.equinox.launcher jar.

Java -jar

This is standard Java part. Java executable has many command line options and -jar is one of them. The curious souls can learn more about packaging and executing jars.

org.eclipse.equinox.launcher

Eclipse has its own OSGi implementation which is known as Equinox. 'org.eclipse.equinox.launcher' is a plug-in as well as executable jar that launches the OSGi Runtime. It is located under plug-ins folder as org.eclipse.equinox.launcher_<version><qualifier.jar> ( for example org.eclipse.equinox.launcher_1.1.0.v20100507.jar).

-application

This '-application' option tells 'org.eclipse.equinox.launcher' that which application has to be launched. The application is identified by its id. The application is discovered using the Application Admin service. The Runtime Application Model explains how it works.

org.eclipse.ant.core.antRunner

Its the application id for the AntRunner application. It is contributed by org.eclipse.ant.core plug-in and its purpose it to run Ant build files.

build.xml

Its the Ant script to build the plug-in. Good news is the we need not be expert in Ant (however it good to have some knowledge about it). The PDE Build can generate this help for us. Right click on the build.properties and select PDE Tools -> Create Ant Build File. This will generate build.xml and javaCompiler...args files. There may be more and specially name of the later may vary depending on the output. entry in the build.properties file.

Putting the pieces together

Assuming that the name of the plugins project is 'com.example.helloworld' the command to build it headlessly will be

example

java -jar C:\eclipse\plugins\org.eclipse.equinox.launcher_1.1.0.v20100507.jar -application org.eclipse.ant.core.antRunner -buildfile C:\workspace\com.example.helloworld\build.xml

Result
This will build the plug-in project according to build.xml script. Since it was generated for us from build.propertied, it is essentially this file that governs the build. Note that build.xml is not generated automatically not kept in sync with build.properties. For any modifications to be reflected, the build.xml file has to be regenerated.
Assuming our plug-in does not have the Bundle-Classpath entry in the Manifest.MF file and source.. and output.. are the only source and output entries in our build.properties. The resultant build of such a plug-in will be in a folder '@Dot' in the project along with the log-file @dot.log .
This is not quite we expected. We were hoping to see a com.example.helloworld_1.0.0.v201006141121.jar kind of file. This happened because the default target (task) will just compile the classes. To make it generate the jar, edit build.xml and make the default target 'build.update.jar' (mentioned in the very first line).

<project name="com.example.helloworld" default="build.update.jar" basedir=".">

This shall generate the com.example.helloworld_<version><qualifier>.jar in the project folder. The build.xml can be modified to have it created in a desired location instead. Also note that the timestamp that replaces 'qualifier' is not the build time but the time when the build.xml was generated.

Admirer of Eclipse

2010-05-22T19:11:00.001+05:30

Helios is looking for 360 friends http://www.eclipse.org/helios/friends.php I am sure with generous Eclipse community, this won't be hard to get. However, we can do something more.

I am suggesting a smaller donation package named 'Admirer of Eclipse'. For a donation of $15 or $20, the donor will get a batch like Friend of Eclipse and Early access to Helios release.

There are two main reasons I came up with this suggestion.

1. There is much less donation from AP region compared to other geographies. This is probably because $35 when converted to local currency becomes a significant figure. I feel may be $15 or $20 is more affordable.

2. One of the major benefit the 'Friends of Eclipse' enjoy is the faster downloads. Now since most Eclipse users at least here in India (and probably adjoining Geos) have 128 kbps or less internet connection. Hence, the larger bandwidth from Eclipse servers is no more a benefit for them.

Please vote a Yes or a No for the idea below (or http://poll.fm/1xfa3 if can't see it)

Remote Debugging Eclipse

2010-05-02T15:05:00.009+05:30

Recently I ran into a nasty bug that will get reproduced only in host Eclipse ¹.The best way to catch them is by remote debugging.

Remote Debugging

Remote debugging is a java feature. Since Eclipse is java application (running inside a JVM) we can remote debug it given the JVM used to launch Eclipse supports it. Most JVMs supports remote debugging from pre-1.4 era.

WebSphere give a nice definition "Debugging a program running on one system while controlling the program from another system is known as remote debugging. The debugger supports remote debugging by allowing you to run the debugger user interface on one system, while running the debug engine on another system. The system running the debugger user interface is known as the local system. The system where the debug engine runs is known as the remote system."

How to remote debug Eclipse?

Start the Eclipse as server

eclipse.exe -vmargs -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044

Connection and Invocation Details page

Creating a Remote Java Application debug config

Start another instance of Eclipse where we will debug the other instance launched in Step 1. Also check out the code that you want to debug. Once this is done, open debug launch configurations and choose 'Remote Java Application' and create a new debug config.

The project text box shall contain the project which has the code that needs to be debugged. The connection type shall be standard socket attach while port will contain the socket address we gave in Step 1. The host is localhost we both instances are running of same machine.

Connecting and attaching to the remote server

Launch the debug config like any other debug config. This will launch the debug mode. Place the breakpoints and do the relevant actions in the server Eclipse instance to hit the.

Debugging

The debug process is same as normal debug. No differences. However, if you change the code then the updated code is not what that would run. Remember the server Eclipse is still running in separate JVM. So what you are getting is only a reflection of the code execution. The debug session will end when the serve Eclipse instance is closed or the client Eclipse is disconnected using the disconnect button in the debug view.

1. Host Eclipse: The default eclipse instance is referred to as Host Eclipse. When self-hosting, a new Eclipse is launched from it, it is referred to as Guest Eclipse or Nested Eclipse Instance.

Eclipse Day India 2010 - thank you

2010-04-26T14:46:00.001+05:30

Bangalore hosted the first edition of Eclipse Day last Friday. And what a gathering it was. More hundred (actually around 110) Eclipse enthusiasts attended the event.

The event was scheduled to have 2 track of sessions after the keynote. But because of Eyjafjallajökull (I actually spent 30 minutes learning its pronunciation ) eruptions grounded most of the European flights, Daniel Megert could not make it for the event. And as we were scrambling for a keynote speaker, Rajesh Thakkar came to our rescue. Thanks Pradeep also persuading him.

Keynote:

Rajesh spoke about 'Agile and Open Source'. He walked us through agile principles and helped us visualize how they fit into open source world. In Eclipse, we are already following many of its principles. We have small iterations. We build and re-factor often. We react to changing requirements rather quickly. Our stakeholders can see what we are building anytime they want. And more importantly Rajesh cautioned us about the myths around the buzzword 'agile'.

After keynote we broke into 2 tracks. All the presentations were well received. The number of interested attendees varied from talk to talk but then we gave them tough choices too of which one to attend. The mood, however, was very exciting.

I wish I could sit and attend all the presentations but had to run around to ensure all talks continue on time and without hiccups. Anyway...am contended as I could meet so many Eclipse enthusiasts. But those who could attend the various talks, do blog about them.

Needless to say such events can not be successful without support from sponsors. So once again a special thanks goes to Eclipse Foundation, IBM Rational Software, Progress Software and Genuitec for supporting the event. We hope the event was up to your expectation and you also benefited from it as much we did.

Thank you all the speakers. You all did a great job and we really appreciate your efforts. A special mention needs to go for Kopal Kothari and Sarika Sinha - the two attendees who volunteered for anchoring the event. Without you it would have been impossible to keep the event on schedule. Since the entry was through registrations, we really thank all the volunteers at the registration desk - Lakshmi, Manju, Kopal, Raksha, Ayushman, Deepak and Satyam. Chetan, Kamalnath and Madhu Samuel did all the photography for the events. Hope they will get the time soon to upload the photographs. Others also who clicked pics please upload it to Flickr and tag is as 'EclipseDayIndia'.

All the presentations will soon be added to slideshare and the link will be made available on event web-site. Meantime, I would request the attendees to fill up a small feedback form.