Sunday, November 11, 2012

Eclipse Plugin Development, Deployment, Distribution : Must read for beginners

This tutorial is not about installing eclipse or the various steps that will help you write a sample eclipse plugin project. There are a lot of tutorials on the net that already do that.

Rather this article is an overview of what eclipse plugin development process is going to be. Something I found no author/forums discussed about( or maybe I wasn't  fortunate enough to find it.).

The process of eclipse plugin development is of  three steps as shown in the figure below:

Three Steps of Deploying an Eclipse Project
3 Steps of deploying an eclipse project


Plugin Project:

This is the real deal. This project is developed on on the eclipse PDE . PDE is Plugin Development Environment. It's your eclipse with SDK for plugin development. Here you will find tools to create a Plugin project, Feature Project and the UpdateSite Project.
This project will have the actual source code of the plugin you create.
The immediate question for any newbie is "How do I distribute this super-duper plugin to the world?" There are two ways actually. The dirty way and the gentleman way.
  • Dirty Way: This way is dirty because its faster to give it to  your pal sitting in the next cubicle. But you wont find world wide adoption that you wished. It creates a jar file that has to be place in a certain directory. Following are the Steps:

    1. Double Click on your project's plugin.xml ==> Overview Subtab ==> Export Wizard.

      Exporting a plugin project

    2. Then you will see a dialog box asking where you want to export . Choose the Directory radio. Enter the directory where your plugin jar needs to go.I have given the location C:\my_plugins\. Let the others be default values.

      Exporting a plugin project

    3. Now when we look into the C:\my_plugins\ directory, there will be a plugins folder under which the plugin jar will be present.The following screen shot makes it clear. In my case I have PexTools_SubMenu_1.0.0.3.jar.

      Exported Plugin jar


    4. Now copy the plugins folder and place it in the dropins folder of your . Meaning, in my case I copy the plugins folder and place it in my C:\eclipse_pde\dropins folder. After restarting eclipse you should be able to view your plugin.

  • Gentleman Way:  The Gentleman Way is to create a Feature Project and then the Update Site Project. So read on to find out.....

Feature project:

  • Create a new Feature Project. A single feature project can have multiple plugins. See the screenshots to guide your way.
    In Step 3, choose the plugin(s) you want to be added into this feature project. In my case I choose my plugin PexTools_SubMenu to be added to this feature.
    Once you click on finish you will have a PexTools_Feature project ready. This will be the input to the the next step.

    New Feature Project
    New Feature Project Step 1

    New Feature Project Page 2
    New Feature Project Step 2

    New Feature Project Step 3
    New Feature Project Step

Update site Project:

  • This is the last step. We will create a new Update Site Project. An update site project will have multiple features.
    See the screen shots below to create an Update Site project.

    Update Site Step 1


    Update Site Step 2
    Update Site Step 2

  • After you click on finish in the screen above,an Update Site Project named PexTools_UpdateSite should have been created. Then open the site.xml and add the feature(s) you want to in this update site. Look at the screenshots below.
    In my case I am adding PexTools_Feature of version 1.0.0.1 into my update site.

    Update Site Step 3: Add feature(s) to your update site.
    Update Site Step 3: Add feature(s) to your update site.
  • After that, click on the build button. This will create the update site artifacts.

    Update Site Step 4: Click on build button

    Update Site Step 5: Update Site Artifacts

Distribution of Update Site XML: 

 Now you are all set to distribute the update site to the world. There are three scenarios here.
  1. Distribute it to the world:  You can upload the update site project on to an FTP server or use a code repository like I have done here and provide the update site. See the "Update Site" of the link that I have provided. It just refers to the site.xml of my update site project. This is the URL that people will use when installing new software in their eclipses.

  2. Test it locally: This is the first thing you should do even before uploading it to the web. The update site will use the file protocol instead of the http or ftp. In my example the update site looked like this --> file:///C:/workspace/PexTools_UpdateSite/site.xml
    Yeah that's hard to type and error prone. I use this technique to get that string. Just right click on site.xml and select Open With -->FireFox. Just copy the URL from the URL box in the browser and test. 

  3. Distribute it as a zip file: If you want the user to download it as a zip file. Then right click on the  update site project , Export as Archive File.  Make Sure You Deselect The .project File Before Clicking On Finish!!. Then you can distribute the zip file to any user who wants your plugin.
One last note, if you make some changes to your Plugin Project,say you fixed a bug, it WONT be immediately reflected in the update site project. For this to happen :
  1. You need to increase the version number of your feature project( like from 1.0.0.3 to 1.0.0.4 ), 
  2. Then go to the update site project and click on Synchronize and Build/Build All buttons in that sequence. 
  3. And again follow one of the above 3 steps. Yeah, even I cringed when i came to know about this.
 
I spent a LOT of time understanding this flow. Hope it makes your life easier...

Please leave a comment below if you liked/hated this post. It will make my day!!

2 comments:

  1. Hi Abhi!
    I'm a research assistant in Computer Science at McGill University in Montreal. I'd like to use this and cite your name for an open source plugin development guide I'm writing. Would that be ok?
    Thank you,
    Caroline Berger (caroline.berger2@mail.mcgill.ca)

    ReplyDelete