Wednesday, October 1, 2008

What’s an example doing in my SDK?

At the planning council meeting today, we had a short discussion about what components put into their SDK features. We have had this debate several times in the past and want to tackle the issue once and for all in the Galileo release.

You figured I had an opinion on this and here is what we did for GEF (and the GMF Runtime).

It is pretty much obvious that the runtime feature has just the runtime plug-ins. No source, documentation or examples.

Now what goes into the SDK features?

Since we are Eclipse plug-in developers using GEF, we need the source and programmer documentation for GEF, so both are in the GEF SDK.

I could probably use the GEF examples as well, but how to handle this?

If I install the examples, I get the examples in my Eclipse workbench. I also get the UI contributions, preference pages, a bunch of wizards, and so on. And I do not really want to create a new GEF logic editor in my development workbench anyway, I want the source code.

This is exactly why the Eclipse platform does not include examples in the SDK; we do not want to pollute our workbench with a bunch of UI contributed by the examples.

What the platform does provide for the plug-in developer is examples as templates in the new plug-in wizards. I can create a new plug-in and use the hello world template or the plug-in with a view template. I get source code examples to assist the plug-in developer.

For plug-in developers using GEF, we wanted to provide something similar. So we added the new plug-in example wizards.

GEF has a PDE examples plug-in in the SDK feature. You can do a File + New + GEF Plug-in Example + Logic. It will load the source code for the GEF logic editor as plug-ins in the workspace.

And there is no examples in my SDK.

p.s. UI pollution by the examples would be solved if projects provided capabilities to disable the example features. We are going to take a run at having each project provide basic capability/activity definitions to allow for their UI contributions to be hidden for Galileo.

5 comments:

Ed Merks said...

To me this is clearly the best way. For examples you generally want them in your work space so you can work with them and this is the best way to get them in there on demand...

In terms of defining and shipping capability definitions, it's likely important that capabilities be defined as a separate feature, so that commercial vendors can use them or define their own, without having to tear apart the features they consume. I can imagine that an uncoordinated effort to universally provide capabilities would result in hundreds of capability categories with no sensible organization...

Kevin McGuire said...

Perhaps this is a good opportunity to exercise p2. The welcome for GEF (or elsewhere too, not sure where) could have a "Get examples" link which triggers a p2 install. While the temptation is to think of the SDK in terms of "pour in everything someone might need, just in case", instead we should think of it as "the essentials, from which it is evident and painless how to get extras".

David Carver said...

Personnaly I would put examples as a separate downloadable feature that somebody could optionally install if they really wanted too. Most of the time when I'm working with something it's the Unit Tests and the existing Code that is the example on how to do something.

Ian Bull said...

Kevin,

Can p2 be utilized to install software (i.e. examples) into my workspace? If so, this would be a great way to ship examples!

Ian Bull said...

Sorry, while you can probably change your bundle pool so things get installed in your workspace, what I meant was, is it easy to setup so users could grab GEF and it would install in their normal bundle pool, but the GEF examples (at least the source) would install in their workspace?