L0016 - The Structure of an Eclipse Plug-in


Published on

This is a detailed description of the different parts that makes up an Eclipse plug-in. The module focuses on the purpose of the different files of a plug-in such as plugin.xml and the OSGi manifest file, MANIFEST.MF. The module also describes how plug-ins are developed in Eclipse with PDE, the Plug-in Development Environment

1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • \n
  • The configuration/config.ini file contains the very basic information needed to launch the product. This includes\nA list of all the plug-ins that should be load at start up.\nThe name of the product to start.\nThe file name of the splash screen to show while the product is started, if any.\nThe plug-ins that makes up an Eclipse RCP application can be divided into three basic groups:\nThe basic Eclipse RCP plug-ins such as org.eclipse.core.runtime and org.eclipse.swt.\n3rd party plug-ins such as BIRT, EMF but also org.eclipse.update.core.\nThe plug-ins with the functionality of the application.\nThe RCP runtime (and OSGi) does not distinguish between the different types of plug-ins. The format of plug-ins are described in the module “L0016 - The Structure of an Eclipse plug-in”.\nThe file system will only include features if the product is feature-based. And unless the product uses the update manager, there is no reason to use features.\n
  • A fragment is recognized in the MANIFEST.MF file by the presence of the Fragment-Host specification.\n
  • In the above example we see the junit plug-in directory. The junit plug-in is available after downloading and installing Eclipse. Every plug-in directory has archive and manifest files. In the above example there are two additional files:\nabout.html - that contains detailed textual description about plug-in\nplugin.properties - file that contains localized strings from plugin.xml\nPlease note that most plug-ins are distributed as .jar files where the above files are embedded with the exception of the .jar file.\nOSGi is able to handle plug-in jar files that in turn contain other jar files. This situation can occur when a 3rd party jar file is needed in an application, but for various reasons it cannot be repackaged – e.g. due to licensing restrictions or a digital signing on the original jar file. When PDE must handle embedded jar files it simply retrieve the files when the bundle is started and then rearranges the class path to include the new locations. This, though, is expensive both in terms of execution time and disk-space and should therefore normally be avoided, if possible.\n
  • Most of these files can exist both in a jar based plug-in (a plug-in packaged as a single .jar file) and in a directory based plug-in. As long as the files from a plug-in are accessed using FileLocator.find(Bundle, IPath, Map) this is completely transparent.\nMore information:\nMANIFEST.MF: http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/reference/misc/bundle_manifest.html\nabout.ini:\nhttp://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/reference/misc/about_customization.html\nSee the module “L0054 - Localization of an Eclipse RCP Application” for information on exactly what can be localized\n
  • \n
  • The declaration files for extension points are based on a restricted form of XSD (as also implied by the extension).\n
  • The complete syntax for the manifest file is found in “OSGi Specifications”. The Eclipse-specific headers are described in “OSGi Bundle Manifest Headers”.\n
  • The plugin.xml file is a regular XML file. The schema for the XML is made up of the schemas for all possible extension points. The syntax is checked in the plugin.xml editor, but not when the plug-in is resolved.\nBefore Eclipse 3.0, the plugin.xml file also included the information that is now put in the MANIFEST.MF.\nThe plugin.xml file shown above defines a new global menu with an action (3.2 edition).\n
  • \n
  • The  PDE has a number of multi-page editors, including the plug-in manifest editor, that share the same basic behavior. The editor has one or more source pages that show the raw file content and one or more form pages that present the same information in a more structured format. \nThe plug-in manifest editor partitions the form information into several pages for less clutter. The best way to learn about the plug-in manifest editor is to visit each page.\n
  • The Dependencies page shows the dependencies that your plug-in has on other plug-ins.  The plug-ins your plug-in currently depends on are shown in the list. You can modify the list by adding more plug-ins (button Add...) or removing them from the list. Changes in this list will prompt PDE to update the plug-in manifest and also configure the build path of the project so that the classes of the imported plug-in are visible to the plug-in under development.\nOnce you add the plug-in reference to the list, you can browse it by selecting Open from the pop-up menu or double-clicking on the entry.\nUse the “Automated Management of Dependencies” sub-page to add all the possible plug-in dependencies to your project:\nContent assist will include all Java classes from these classes as well as all classes from required plug-ins\nThe required plug-ins will automatically be updated\n
  • The Runtime page describes which Java packages of the plug-in may be exported to other dependent plug-ins. Only the listed packages can be used by other plug-ins.\nThere is a special case: it is possible to make certain packages visible only to a limited set of other plug-ins (“Package Visibility”). This feature can be used between very closely coupled plug-ins to allow a greater visibility than normally. One such case is for test suites, where the test code is kept in a separate plug-in – to avoid getting it into the production system – but it often needs a more enhanced interface in order to test many features. Note though that fragments are a better solution in this case.\n
  • The Extensions page is used to browse and edit plug-in extensions. Extensions are the central mechanism for contributing behavior to the platform. Unless your plug-in is a simple Java API library made available to other plug-ins, new behavior is contributed as an extension.\n
  • The Extension points page is used to browse and edit extension points defined by the plug-in. Our plug-in's extension points can be used by the plug-in itself or another plug-in.\nPlease note that the name of the extension point is localized – the text is found in plugin.properties with the key ExtPoint.acceleratorConfigurations.\nThe XML file that describes the complete extension point is found as the file schema/acceleratorConfigurations.exsd. More about this in the module “L0015 - Making Extension Points”.\nTo see more about the different plug-ins that make up the Eclipse IDE, browse the “Plug-ins” view of the PDE perspective.\n
  • The Build page shows information about the generated runtime libraries. When packaged, platform plug-ins deliver all of their Java classes in JAR libraries. This page defines how the classes that are in source folders during the design time are packaged into the libraries. One source folder and one library have already been set during the project creation by the wizard. You can define more on this page.\nAlthough a plug-in can be divided into multiple .jar files, this should normally be avoided as it means the plug-in must be distributed as a directory instead of a .jar file.\nThe source build side of the tab is only relevant if you wish to distribute source plug-ins either to the public (not so likely) or to other parts of your company that might build on top of your work.\n
  • When an IDE or RCP application or product is started under PDE – sometimes called self-hosted – the new process is given a bundle path that includes all development plug-ins as well as the target system plug-ins. Check the osgi.bundles setting in {your-workspace}/.metadata/.plugins/org.eclipse.pde.core/{launch-name}/config.ini.\n
  • \n
  • L0016 - The Structure of an Eclipse Plug-in

    1. 1. The Structure of an Eclipse Plug-inThis is a detailed description of the different parts that makes up anEclipse plug-in. The module focuses on the purpose of the different filesof a plug-in such as plugin.xml and the OSGi manifest file, MANIFEST.MF.The module also describes how plug-ins are developed in Eclipse withPDE, the Plug-in Development EnvironmentRedistribution and other use of this material requires written permission from The RCP Company.L0001 - 2010-11-27
    2. 2. Basic Eclipse File StructureAn Eclipse IDE or RCP-based product consists of a rather large number offilesThe more important are the following  configuration/* – the configuration of the product  configuration/config.ini – the master configuration file  plugins/* – the plug-ins of the product  features/* – the features of the product  name.exe – the executable that starts the application  name.ini – application options2 L0001 - 2010-11-27
    3. 3. What is an Eclipse Plug-inA plug-in is the smallest functionality that is managed in the EclipseplatformPlug-ins are described via a number of configuration filesPlug-ins have different forms under development and runtimePlug-ins are sometimes deployed individually  If you need update support, plug-ins must always be deployed as parts of a featureA fragment has the same structure as a plug-in with very few changes3 L0001 - 2010-11-27
    4. 4. What Makes Up a Plug-in at Runtime?Two types of plug-ins:  Jar-based  Directory-basedDirectory based plug-ins used whencomponents outside the Eclipse run-timecomponent need access to files of the plug-inThis directory based plug-in consists of:  about.html – textual description of the plug-in  junit.jar – archive that contains plug-in code  META-INFMANIFEST.MF – the identity of the plug-in  plugin.properties – localized strings  plugin.xml – extension points and extensions  In this case the jar file must be accessible from the tested application4 L0001 - 2010-11-27
    5. 5. Runtime Files of a Plug-inOSGi files  META-INF/MANIFEST.MF – description of OSGi bundle  .options – options for this specific plug-inGeneral plug-in files  plugin.xml and fragment.xml – description of extension points and extensions of a plug-in  plugin.properties and fragment.properties – localized strings for the previous files5 L0001 - 2010-11-27
    6. 6. Runtime Files of a Plug-inProduct-specific files  splash.bmp – splash screen used at product start-up  about.ini – description of a product  about.properties – localized strings for about.ini  about.mappings – very simple macro facility for about.properties  about.html – additional information about plug-in including licensing  plugin_customization.ini – options for different plug-ins  plugin_customization.properties – localized strings for plugin_customization.ini*.jar – jar files with typically 3rd party functionality6 L0001 - 2010-11-27
    7. 7. Development-time Files of a Plug-inEclipse Project files:  .project – basic description of Eclipse project  .classpath – the Java class path for a Java Eclipse project (and thus also a PDE project)  .settings – preference store for project level preferences – includes all property settings for the projectProduct specification files  *.product – product declaration filesBuild declarations  build.properties – build information for Ant with content of the resulting jar files for the projectExtension Points  *.exsd – extension point declaration files7 L0001 - 2010-11-27
    8. 8. MANIFEST.MF FileThe OSGi manifest file describes the identify of the plug-in and thedependencies on other plug-insManifest files are very seldom edited directly! Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: %pluginName Bundle-SymbolicName: com.rcpcompany.training.cm33.core; singleton:=true Bundle-Version: 2.1.0 Bundle-ClassPath: . Bundle-Vendor: %providerName Bundle-Localization: plugin Bundle-RequiredExecutionEnvironment: J2SE-1.5 Export-Package: com.rcpcompany.training.cm33.core, com.rcpcompany.training.cm33.core.util Require-Bundle: org.eclipse.core.runtime, org.eclipse.emf.ecore;visibility:=reexport Bundle-ActivationPolicy: lazy8 L0001 - 2010-11-27
    9. 9. plugin.xml File (3.2 edition) <extension point="org.eclipse.ui.actionSets"> <actionSet label="Sample Action Set" visible="true" id="Demo.actionSet"> <menu label="Sample &amp;Menu" id="sampleMenu"> <separator name="sampleGroup"> </separator> </menu> <action label="&amp;Sample Action" icon="icons/sample.gif" class="demo.actions.SampleAction" tooltip="Hello, Eclipse world" menubarPath="sampleMenu/sampleGroup" id="demo.actions.SampleAction"> </action> </actionSet> </extension>9 L0001 - 2010-11-27
    10. 10. plugin.xml File (3.3 or later edition) <extension point="org.eclipse.ui.commands"> <command id="com.rcpcompany.demo.menu33.commands.HelloWorld" name=”&amp;Sample Action” /> </extension> <extension point="org.eclipse.ui.commandImages"> <image commandId="com.rcpcompany.demo.menu33.commands.HelloWorld" icon="icons/sample.gif” /> </extension> <extension point="org.eclipse.ui.handlers"> <handler class="demo.actions.SampleHandler" commandId="com.rcpcompany.demo.menu33.commands.HelloWorld” /> </extension> <extension point="org.eclipse.ui.menus"> <menuContribution locationURI="menu:org.eclipse.ui.main.menu"> <menu id="sampleMenu" label="Sample Menu" mnemonic="M"> <command commandId="com.rcpcompany.demo.menu33.commands.HelloWorld" id="com.rcpcompany.demo.menu33.commands.HelloWorld.mc.sampleMenu” /> </menu> </menuContribution> </extension>10 L0001 - 2010-11-27
    11. 11. Plug-in Editor Double-click on the plugin.xml or MANIFEST.MF opens the editor Almost all plug-in details can be changed in the editor Overview page displays basic plug-in information11 L0001 - 2010-11-27
    12. 12. Dependencies Page Displays dependant plug-ins  Created by tools when the plug-in type is chosen  New dependences can be added12 L0001 - 2010-11-27
    13. 13. Runtime Page Displays runtime information such as plug-in classpath Populated by the tools based on inputs from wizards Additional libraries can be added to the classpath13 L0001 - 2010-11-27
    14. 14. Extensions Page Displays plug-in extensions  Created by the tool based on the plug-in type  Extensions can be added14 L0001 - 2010-11-27
    15. 15. Extension Points Page Displays plug-in extension points  This example is taken from the org.eclipse.ui plug-in15 L0001 - 2010-11-27
    16. 16. Build and build.properties Pages Interface to the build.properties file  specifies which .jar files to generate Also describes which non-Java files that are part of the generated .jar file16 L0001 - 2010-11-27
    17. 17. Development Time and Runtime The format and content of a plug-in differs slightly between development time (in PDE) and runtime  A development time plug-in is valid as a runtime plug-in  A runtime plug-in does not include any sources – whether they are Java or XML files  Normally a runtime plug-in is packaged as a single jar file, except  when the plug-in contains multiple jar files – e.g. 3rd party  when the plug-in contains writable files – almost never  The exact content of the runtime edition of a plug-in is controlled in the Build tab of plugin.xml editor  If your icons are red and translations are missing, then you probably forgot to tick files in the Build tab…17 L0001 - 2010-11-27
    18. 18. More Information Platform Plug-in Developer Guide  http://help.eclipse.org/help33/index.jsp OSGi Specifications  http://osgi.org/osgi_technology/download_specs.asp?section=2 “OSGi Bundle Manifest Headers”  http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/ reference/misc/bundle_manifest.html “Eclipse Plug-in Migration Guide”  http://help.eclipse.org/ganymede/nav/2_318 L0001 - 2010-11-27