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.

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.

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

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.

Eclipse Day India 2010

2010-04-13T02:30:00.000+05:30

Eclipse Day India 2010 will be held on April 23, 2010 at Monarch Luxur, Bangalore. Around 150 Eclipse enthusiasts from over 35 companies are expected to attend this event. This shows Eclipse is getting lot of love from Bangalore and many companies are either using it for their development needs or relying on it as a base for their products.

The agenda for the event has been announced. Dani will be delivering the keynote address to Eclipse Day India attendees.

If you are attending the event do meet up in the networking lobby. We won't have a frosty beverage but nice coffee and yummy food instead :-) I am very excited about this event and eager to know the ways in which developers are using Eclipse in their projects.

Unconference

There will be an hour session where attendees can share their ideas, experiences and knowledge of Eclipse and related technologies. So please do come forward and share your stories.

Feature based launching

2010-04-03T23:56:00.000+05:30

Recently we made an conscious effort for making features first class citizens in target definitions. As a part of that effort PDE introduced Feature based launching. This is available in 3.6 M6 build.

Till now there was only a not so elegant way to self-host using features - Feature-based self-hosting. This has now been deprecated.

Feature-based launching

An eclipse application can now also be launch just by picking the feature to launch with. This will be very helpful as in most scenarios as we have plug-ins grouped under features and we will want to have all plug-ins in a feature launched.

(This is M7 look. M6 look differs only with an extra version column)

How will it work?
It will work much like plug-ins only. However, few important points.

The checkbox "Use feature from workspace if available" if self-explanatory. When checked, workspace feature will be used (instead one from target) to find the required plug-ins.
Plug-in Location can be Default, Workspace or External (that is, Target Platform). Default means the value will be Workspace or External as selected using "Default Plug-in Location" option under "Restore Defaults" button.
Plug-in Location means the location from where the plug-ins of a certain feature will be resolved. Thus, a feature might be getting picked from Target but its plug-ins can be picked from the Workspace instead.
"Add Required Features" will only add (select) those features to the launch config which are mentioned as dependent features in feature manifest. It will not try to see if the dependent plug-ins map to any feature.
Dependent plug-ins will be implicitly added to the launch. These are the plug-ins which do not belong to any feature and but the plug-ins of the selected features depend on them. e.g. com.ibm.icu
These implicit plug-ins will be picked from same location from where the dependent plug-ins were picked from. If a finer control is needed then good old plug-in based launch is more suited.

Do report bugs if you find anything is not working as mentioned or expected.

Eclipse Day Submissions

2010-02-16T15:33:00.000+05:30

Thanks everyone for showing such enthusiasm for Eclipse Day. We already have received some nice proposals. And as requested by many we are relaxing the last date to submit the talk proposals till Feb 28, 2010.

You may find the submitted proposals here http://bit.ly/EclipseDaySubmissions

Did you register for Eclipse Day India 2010?

2010-02-09T00:51:00.000+05:30

Registrations opened today for Eclipse Day India 2010 and it has been a great response. Half the seats already booked on day one. Attendees from over 20 companies have already registered and the number will only go up further only so register quickly.

We will be publishing the agenda by mid-March. So if you are an Eclipse enthusiast then it will be a great opportunity to not only attend some really nice presentations but also network with the community.

And if you are a company which consumes Eclipse, then what better occasion to show your support by becoming a joint sponsor. IBM Rational has already come forward to joint sponsor event.

We would love to hear from you if you have been doing some nice work with Eclipse and plug-ins. Do submit your thoughts at http://EclipseDay.in.

Eclipse Day India 2010

2010-01-15T21:06:00.000+05:30

Eclipse Day India 2010

I and Prakash are organizing Eclipse Day India 2010 on Friday, April 9, 2010. Since this is the first time it is being organized in India, we are keeping the theme fairly broad and simple - Eclipse Plug-in Development. You can find the details at http://eclipseday.in.

Sponsorship

Unlike Eclipse Demo Camp last year, this will be on a slightly bigger scale and thus we need sponsors. If you wish to support the event by extending a sponsorship please do get in touch with us. This will be a great opportunity to reach a gathering of more than 100 Eclipse developers and users from around a dozen companies.

Call for Talks

The Eclipse Day India is now inviting proposals for talk. Last day to submit your proposals is Feb 15, 2010. See the details on the event wiki.

Attendee Registration

The event is FREE. There is no cost to attend however preregistration is must due to limited seats. Registrations open Feb 1, 2010.

I came third

2010-01-06T00:43:00.000+05:30

This came as a complete surprise to me. Am at number three in 'Most contributed patches approved for IP Log' list.

Reproducing the list from Denis Roy's post.

Most contributed patches approved for IP Log

68 Ian Tewksbury       @ibm.com
51 Matthew Piggott     @piggot.ca
46 Ankur Sharma        @ibm.com
46 Chris Jaun          @ibm.com
44 Ian Bull            @eclipsesource.com
40 Tim Buschtoens      @eclipsesource.com
37 Pawel Pogorzelski   @ibm.com
36 Benjamin Cabé       @sierrawireless.com
31 Danny Ju            @oracle.com
29 Raksha Vasisht      @ibm.com

Am also glad for Raksha (who is part of same team as I am) that she too made it in Top Ten. We got committers right in September '09 so playing in a bigger league now. Hope to report (if not resolve) lots of bugs in 2010 :)

Writing an RCP application using e4 modeled UI - part II

2009-12-31T06:00:00.000+05:30

Understanding what we did and why

In the previous post we wrote a very minimalistic RCP application using e4 modeled UI. Before adding more stuff to it, lets quickly revisit few steps and try to make sense of them.

In Step 1 we unchecked the Generate an activator button. This was because right now we don't want to do anything on bundle start or stop events. We will later add one if we find the need to do so.

In Step 2, we add a dependency to org.eclipse.core.runtime plug-in. This was to bring the extension org.eclipse.core.runtime.products in visible scope. If we don't add this dependency, we will get prompted to add it when we add the extension.

We also gave the value product to the extension id. This was to get the product registered as projectname.product. That is why we created a new product config in Step 5, the product org.example.e4.rcpapp.product was already available to us.

e4 provides an out of the box application which understands the modeled UI. This application is org.eclipse.e4.ui.workbench.swt.E4Application which is why we assigned it to the application property of our product.

The applicationXMI property is what points to the UI model which the E4Application will use to render the UI. The format for the value is the plugin-name/project-relative-path. The file extension doesn't really matter. But an xmi extension will make it open the Toolkit Model Editor.

In Step 3, we had to manually add and modify the Application.xmi file. The New wizard doesn't have a option for it yet. Bug 284413 shall address the issue.

In Step 4, we gave proper shape to the model.

Application - this node represents the complete application. It will contain all UI elements plus their handlers, etc. Basically everything has to be child of this node.

Window - represents the visible window that will form the RCP application GUI. Whatever Label we give to it, is what we will see in the window title bar. Lets play with it a bit. Change the Label property to give it a new title. Give the X and Y property as 10 each. Save the editor and launch the application. You will see the application now has the new title and it shows up very close to the top-left corner of the screen. The X and Y properties represents the distance from the top-left corner of the screen.

Part Sash Container - is a container for our Part. In e4 both view and editor are treated equally as Part. All the children Parts will share the space among them.

Part Stack - is a collection of sibling Parts. Only one visible as a time - like we deck various views currently.

Part - represents a view or a editor. As usual, the Label property will control the name getting displayed on the view tab. We also added it a property URI and gave it a value platform:/plugin/org.example.e4.rcpapp/org.example.e4.rcpapp.views.MyView. This looks like a class name because it is a class name. We don't really need it as of now, but without it you will get a error and just to suppress it I added it. Getting an error on your first e4 RCP app won't look too elegant ;) In next post we will added this class and use it to create UI in the Part space.

Step 5 created a product configuration to help invoke the application. Nothing new here.

Step 6 created a run configuration using the product created in Step 5.

Step 7 simple launched this run config.Only point to note here would be the Plug-ins tab in Run configuration shall select all the target plug-ins. This is because the Add Required Plug-ins button can not yet cope with the Dependency Injection used by modeled UI. Not doing so will run you into NPE at org.eclipse.e4.workbench.ui.internal.E4Workbench.init(E4Workbench.java:93).

Next

We will add more Parts and render some useful UI in it.

Writing an RCP application using e4 modeled UI - part I

2009-12-31T01:23:00.002+05:30

Prakash was couple of hours quicker on posting the same topic here. I have a slightly different approach and may be more to add. Lets see.

Step 1: Create a simple plug-in project.

Open the plug-in wizard and create a new plug-in project. Let's give a name org.example.e4.rcpapp. Be sure to uncheck the Generate an activator option. Click Finish. Do not go to template page (they are not yet updated for e4).

Step 2: Adding product extension.

Open the manifest editor and go to Dependencies tab. Add org.eclipse.core.runtime as required plug-in. Now open the Extensions page. Add a new extension org.eclipse.core.runtime.products.

Select the extension and give it a ID product in extension details section.

Right click the extension and select New -> Product. Select the product and give it a nice name - e4 RCP app. Change the application id to org.eclipse.e4.ui.workbench.swt.E4Application.

Now right click the product in extension section and add two new properties. In the extension section give the name and values like this

Name : appName

Value : Hello e4

Name : applicationXMI

Value : org.example.e4.rcpapp/Application.xmi

After this your plugin.xml will look like this

<plugin>
   <extension
         id="product"
         point="org.eclipse.core.runtime.products">
      <product
            application="org.eclipse.e4.ui.workbench.swt.E4Application"
            name="e4 RCP app">
         <property
               name="appName"
               value="Hello e4">
         </property>
         <property
               name="applicationXMI"
               value="org.example.e4.rcpapp/Application.xmi">
         </property>
      </product>
   </extension>
</plugin>

Step 3: Application.xmi

Create a new file to the root of the project and call it Application.xmi. It will open by default in a Toolkit model editor with errors (because it doesn't have the expected header). The editor will show a button Open with Text Editor. Click it and the file will open in a text editor. Add following skeleton to it. Save and close it.

<?xml version="1.0" encoding="ASCII"?>
<application:Application xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:application="http://www.eclipse.org/ui/2008/UIModel">
</application:Application>

Reopen the file and it will now open properly.

Step 4: Creating Modeled UI

When you right click any node in this editor, there will options to add a new Child and/or Siblings. The Properties view will show the properties of each node. If it is not already visible you can invoke it by selecting the node and choosing Show Properties View option from the context menu.

Select the Application node and add a new child Window to it. See its properties and give it a nice name in the Label property like Hello e4.

Select the Window node and add a child Part Sash Container.
Select PartSashContainer node and add a child Part Stack.
Finally select PartStack node and add a child Part to it. Visit the Properties view for the Part node and give it a name in the Label property like My view. And in the URI property give a path platform:/plugin/org.example.e4.rcpapp/org.example.e4.rcpapp.views.MyView

Save the editor and it shall now look like this.

To be sure that we did everything right, open the Application.xmi in text editor and its contents should look like this

<?xml version="1.0" encoding="ASCII"?>
<application:Application xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:application="http://www.eclipse.org/ui/2008/UIModel">
  <children xsi:type="application:Window" label="Hello e4">
    <children xsi:type="application:PartSashContainer">
      <children xsi:type="application:PartStack">
        <children xsi:type="application:Part" URI="platform:/plugin/org.example.e4.rcpapp/org.example.e4.rcpapp.views.MyView" label="My View"/>
      </children>
    </children>
  </children>
</application:Application>

Step 5: Product Configuration

Create a new Product Configuration. Select the product org.example.e4.rcpapp.product from the combo by enabling the Use an existing product option in the New Product Configuration wizard.

The product editor will now open and will look like this

Step 6: Creating a Run Configuration

Open the Run Configurations wizard and create a new Eclipse Application config. Name it rcpapp.product.
Choose the product org.example.e4.rcpapp.product in the Run a product option.

Go to Plug-ins tab and make sure all workspace and enabled target plug-ins option is selected in the Launch with combo.

Step 7: Launching the RCP Application

Click Run button in run configuration to execute the RCP application. Your first e4 RCP application will look like this

Next

In the following posts we will revisit what we did above and try to see why we did it so.

Note to e4 gurus and committers

This series is post is outcome of hit-and-trial self learning. Please do add you views or point out any mistakes you see.

LinkedIn IT Trends and Compensation Report (Aus-India) 2009

2009-12-23T23:34:00.000+05:30

LinkedIn’s Technology Trends & Compensation Study Australia - India Report for 2009 was released recently. You may download the PDF from here. Apart from various trends, I found a couple for slides with a mention of Eclipse too.

1. Eclipse is the 4th most popular development tool.

I was expecting Eclipse to be in top 5 so being number 4 is not so disappointing. I feel some of the survey participants might have counted Eclipse under 'Other open source dev tools' which is at number 2.

2. 46% developers 'very satisfied' with Eclipse.

Eclipse got second highest votes for 'very satisfied'. Surprisingly second to Apple!! What can I say. May be because I don't have a iPhone :-) But even more shocking was SAP better than Apple and Eclipse in average scores. Now I have seen only one SAP application and that sucks bad. Perhaps they really are doing a fantastic job.

Since the report from Australia-India geo its a partial view. Am sure this pictures differs a lot from the one at global level.

Heap Status

2009-12-07T21:28:00.000+05:30

If you wish to keep an eye on heap status of your eclipse instance then a quick way to do it is 'Heap Status' preference. You don't need any memory profiler for this.

This starts displaying the heap status in the status bar.

The garbage can icon is for running the Garbage Collection. It basically makes call to System.gc() and System.runFinalization()

source. and output.

2009-11-21T03:19:00.003+05:30

The source and output properties in build.properties control the folders to be compiled and where to place the resulting output. The eclipse help briefly talks about it.

    * source.<library> - lists source folders that will be compiled (e.g. source.xyz.jar=src/, src-ant/). If the library is specified in your plug-in.xml or manifest.mf, the value should match it;
    * output.<library> - lists the output folder receiving the result of the compilation;

Source Folders and Output Folders

Source and Output folder have already been discussed in this post. Only the source folders gets compiled and the generated class files get stored in the corresponding output folder. A project can have one or more source folder. If a source folder does not have a output folder attached to it explicitly, its output will go to the default output folder. The .classpath file stores all this information.

source.. and output..

The real syntax is source.<library> and output.<library> where <library> is generally the name of the jar. Here the second dot signifies the default library. Any source folder assigned to it gets it output reside in the root when the plug-in is build. The output.. entry tells the PDE Build where to pick the classes for source.. from.

Typical entries look like this

source.. = src/
output.. = bin/

When a plug-in with above entries is build the structure of the plug-in jar will look like this

org.example.sample_1.0.0
│   plugin.xml
│
├───icons
│       sample.gif
│
├───META-INF
│       MANIFEST.MF
│
└───org
    └───example
        └───sample
            │   Activator.class
            │
            └───actions
                    SampleAction.class

More complex plug-ins have more than one source folder. org.eclipse.pde.core is one such plug-in. It is good practice to assign separate output folder for separate source folders. This is not mandatory.
Lets assume src and src_an are the two source folders and their corresponding output folders are bin and bin_ant. Then a build.properties like

source.. = src/
output.. = bin/
source.ant_tasks/anttasks.jar = src_ant/
output.ant_tasks/anttasks.jar = bin_ant/

will create a plug-in which will look something like this

org.example.sample_1.0.0
│   plugin.xml
│
├───ant_tasks
│       anttasks.jar
│
├───icons
│       sample.gif
│
├───META-INF
│       MANIFEST.MF
│
└───org
    └───example
        └───sample
            │   Activator.class
            │
            └───actions
                    SampleAction.class

The contents of the src_ant folder will get compiled and jared in to anttasks.jar inside ant_tasks folder because of the source.ant_tasks/anttasks.jar = src_ant/ entry.

Classpath vs source/output entries

The source folder and output folder information is already available in class path then why source/output entries are needed? The classpath entries are used to compile source code. But the PDE Build relies on the source/output entries while building (or exporting) the plug-ins. Suppose a plug-in A refers to a class C in plug-in B. Then while building the plug-in A PDE Build will look into build.properties of plug-in B to locate the C.class.

Rules of using source. and output. entries

Every source folder should appear in a source. entry.
A source folder can appear in one and only one source. entry.
The source and output folders are specified as their path relative to the root of the project.
All source folders whose output folder is same should belong to same source. entry.
The corresponding output folders should be mentioned in the corresponding output.entry.

Note that should in above rules means that rule is a good practice and not an obligation but if not followed the result of PDE Build might be unexpected.

Execution Environment and javac entries

2009-10-21T06:51:00.003+05:30

Execution Environment

Execution Environments have been explained in detail in this article. And from PDE API tooling perspective it has been explained here. In one line, EE represents the JRE. It is a set of properties, each marking a level of compliance. I am reproducing this table from 'Setting the Compilation Environment' help page.

Environment	Source	Target
CDC-1.0/Foundation-1.0	1.3	1.1
CDC-1.1/Foundation-1.1	1.3	1.2
OSGi/Minimum-1.0	1.3	1.1
OSGi/Minimum-1.1	1.3	1.2
JRE-1.1	1.1	1.1
J2SE-1.2	1.2	1.1
J2SE-1.3	1.3	1.1
J2SE-1.4	1.3	1.2
J2SE-1.5	1.5	1.5
JavaSE-1.6	1.6	1.6
PersonalJava-1.1	1.1	1.1
PersonalJava-1.2	1.1	1.1
CDC-1.0/PersonalBasis-1.0	1.3	1.1
CDC-1.0/PersonalJava-1.0	1.3	1.1
CDC-1.1/PersonalBasis-1.1	1.3	1.2
CDC-1.1/PersonalJava-1.1	1.3	1.2

There are more properties and are provided by org.eclipse.jdt.core

org.eclipse.jdt.launching plug-in provides an extension point (id = org.eclipse.jdt.launching.executionEnvironments) for contributing EEs. JDT Launching plug-in also extends it and provides the EEs that are listed in the above table. If you really want to see the code then check out JavaCore.java and CompilerOptions.java in org.eclipse.jdt.core plug-in.

Manifest.MF

The execution environment for a bundle can be defined in the Manifest.MF file. A typical entry for Java 1.4 environment will look like this.

Bundle-RequiredExecutionEnvironment: J2SE-1.4

The manifest editor provides an easier way on the Overview tab.

Execution Environment section on Overview page of Manifest Editor

The Add button opens a selection dialog with the list of available execution environments (contributed to the extension point org.eclipse.jdt.launching.executionEnvironments). By default the list is same as those listed in the table above.

jre.compilation.profile

The execution environment in build.properties is mentioned using the jre.compilation.profile entry. It takes same value as BREE entry in manifest.MF. Thus, the entry for Java 1.4 will look like this.

jre.compilation.profile = J2SE-1.4

javacSource, javacTarget and javacWarnings

These entries can be used to override the jre.compilation.profile entry in build.properties. A certain EE mandates a particular version for Java source and generated class file compliance. These versions can be overridden using these entries. These entries can be used without jre profile entry as well. If you just want to specify the java source version then only javacSource entry will suffice.

Looking at the table above we can see that J2SE-1.4 is Java source at version 1.3 and class files version 1.2 compliant. This can be mentioned in build.properties as

javacSource = 1.3
javacTarget = 1.2

Please note that the above two entries are not equivalent to jre profile entry for J2SE-1.4. This is because an EE is other properties too like system packages, boot delegation, assert and enum identifiers. See the schema description for the EE extension point discussed above.

Eclipse uses batch compiler to build the plug-ins. It is located inside org.eclipse.jdt.core. Since version 3.2, it is also available as separate download - ecj.jar - Eclipse Compiler for Java. The batch compiler accepts many options and a list and details can be found here. The javacSource and javacTarget entries map to -source and -target options.

javacWarnings.<library> entry is used to pass the warning options (-warn) to the compiler. The entry to suppress warnings for assert and enum identifiers in library.jar will look like this

javacWarnings.library.jar = -assertIdentifer, -enumIdentifier