Jump to: navigation, search

Difference between revisions of "SMILA/Documentation/HowTo/Create a bundle (plug-in)"

(Add SMILA category)
 
(24 intermediate revisions by 7 users not shown)
Line 1: Line 1:
This pages describes how to create a new bundle for SMILA. The following steps must be performed to create the project base:
+
This page describes how to create a new bundle for SMILA.The description on how to add a test bundle to test the components of the new bundle can be found in [[SMILA/Development Guidelines/Create a test bundle (plug-in)|How to create a test bundle (plug-in)]].
  
== Selecting the new Project Wizard ==
+
== Create the bundle  ==
  
[[image:NewProject-Brox.png]]
+
The following steps must be performed to create the project base:  
  
== Starting Page of the Plug-in Project Wizard ==
+
#Launch Eclipse and select your SMILA workspace.
 +
#Select ''File > New > Project'' and click ''Plug-in Project''.
 +
#Click ''Next''. <br>Now you have to fill in various metadata and settings for your plug-in project. You may as well edit some of the settings later on by opening the <tt>MANIFEST.MF</tt> with the ''Plug-in Manifest'' editor.
 +
#Enter a project name (you should use a fully qualified name, for this example we will use <tt>org.eclipse.smila.example.bundle</tt>).
 +
#Add <tt>code</tt> as a parent to the source and output folder:
 +
#*Set ''Source folder'' to <tt>code/src</tt>.
 +
#*Set ''Output folder'' to <tt>code/bin</tt>.
 +
#Set ''Target Platform'' to <tt>an OSGi framework: Equinox</tt>.
 +
#Click ''Next''.
 +
#Fill in the metadata information of the new bundle. Set the plug-in's name as ID, your bundle's version, a reasonable bundle name and the information about the provider (i.e. you). For our example we select:
 +
#*ID: <tt>org.eclipse.smila.example.bundle</tt>
 +
#*Version: <tt>1.1.0.qualifier</tt>
 +
#*Name: <tt>Example Bundle Plugin</tt>
 +
#*Provider: <tt>Eclipse RT SMILA project</tt>
 +
#*Exection Environment: <tt>JavaSE-1.6</tt>
 +
#Unless you need an activator, uncheck this option.
 +
#Click ''Next''.
 +
#Unless you want to use any of the given templates to create your plugin, uncheck the option.
 +
#Click ''Finish''.
  
[[image:projectWizard1.png]]
+
== Check the result  ==
  
== Defining Plug-in Content ==
+
When you're done with the above, your actions should have resulted in a new project with (in our example) the name of <tt>org.eclipse.smila.example.bundle</tt>, that now shows up in your workspace. Just check your ''Package Explorer'' for the new bundle. In it, there should be an empty <tt>code/src</tt> package, a <tt>META-INF</tt> folder containing a <tt>MANIFEST.MF</tt> file and a <tt>build.properties</tt> file. Open the <tt>MANIFEST.MF</tt> file and while clicking through the panels you will recognize most of the settings, we made above.
  
[[image:projectWizard2.png]]
+
It is usually useful to add export all packages from your bundles, so that other bundles can import it. To do this, go to the ''Runtime'' tab of the <tt>MANIFEST.MF</tt> editor and add the packages to the ''Exported-Packages'' list. Additionally, it is good practice to maintain a version number (e.g. <tt>1.0.0</tt>) for each package.
  
== Package-Explorer view ==
+
Now that you've created your bundle, you can add your components as you like but do not forget to [[SMILA/Development Guidelines/Create a test bundle (plug-in)|add a test bundle]].
  
[[image:packageExplorer.png]]
+
== Add bundle to launch configuraton ==
 +
 
 +
To add your new bundle to the <tt>SMILA</tt> launch configuration in the workspace, so that you can test and debug it in a running SMILA system:
 +
* Open ''Run'' -> ''Run Configurations...'' or ''Debug Configurations...''
 +
* In the list on the left side, select ''OSGi Framework'' -> ''SMILA''
 +
* In the ''Bundles'' list on the right side, look for your bundle and select it. Defaults for ''Start level'' and ''Auto-Start'' are OK for pipelet bundles. For bundles containing OSGi services (e.g. workers or HTTP handlers) set ''Auto-Start'' to <tt>true</tt> so that the service gets activated at system start.
 +
 
 +
== Create a Working Set ==
 +
 
 +
You may want to create a working set for your own bundles to make it easier to find them among all those SMILA bundles:
 +
 
 +
*In the ''Package Explorer'' view on the left side, open the menu (click on the small triangle in the upper right corner) and select ''Select Working Sets...''
 +
*In the following dialog, click ''New...''
 +
**Select ''Java'', click ''Next >''
 +
**Enter a name (e.g. "My Bundles"), select you bundle in the left list and click ''Add -->'', then click ''Finish''
 +
*Select the created working set in the list and click ''OK''
 +
Now only your own bundle will be displayed in the Package Explorer. To view all bundles again, open the explorer view menu again and choose ''Deselect Working Set''. To add more bundles to an existing working set, choose ''Edit active working set'' when one is selected. You can also create more working sets (e.g. for subsets of SMILA you need to see) as you like. Just try it out (:
 +
 
 +
== Integrating the new bundle in the build process ==
 +
To include the just created bundle in the build you should follow the instructions on [[SMILA/Development_Guidelines/How_to_integrate_new_bundle_into_build_process|how to integrate a new bundle into the build process]].
  
 
[[Category:SMILA]]
 
[[Category:SMILA]]

Latest revision as of 05:04, 31 July 2012

This page describes how to create a new bundle for SMILA.The description on how to add a test bundle to test the components of the new bundle can be found in How to create a test bundle (plug-in).

Create the bundle

The following steps must be performed to create the project base:

  1. Launch Eclipse and select your SMILA workspace.
  2. Select File > New > Project and click Plug-in Project.
  3. Click Next.
    Now you have to fill in various metadata and settings for your plug-in project. You may as well edit some of the settings later on by opening the MANIFEST.MF with the Plug-in Manifest editor.
  4. Enter a project name (you should use a fully qualified name, for this example we will use org.eclipse.smila.example.bundle).
  5. Add code as a parent to the source and output folder:
    • Set Source folder to code/src.
    • Set Output folder to code/bin.
  6. Set Target Platform to an OSGi framework: Equinox.
  7. Click Next.
  8. Fill in the metadata information of the new bundle. Set the plug-in's name as ID, your bundle's version, a reasonable bundle name and the information about the provider (i.e. you). For our example we select:
    • ID: org.eclipse.smila.example.bundle
    • Version: 1.1.0.qualifier
    • Name: Example Bundle Plugin
    • Provider: Eclipse RT SMILA project
    • Exection Environment: JavaSE-1.6
  9. Unless you need an activator, uncheck this option.
  10. Click Next.
  11. Unless you want to use any of the given templates to create your plugin, uncheck the option.
  12. Click Finish.

Check the result

When you're done with the above, your actions should have resulted in a new project with (in our example) the name of org.eclipse.smila.example.bundle, that now shows up in your workspace. Just check your Package Explorer for the new bundle. In it, there should be an empty code/src package, a META-INF folder containing a MANIFEST.MF file and a build.properties file. Open the MANIFEST.MF file and while clicking through the panels you will recognize most of the settings, we made above.

It is usually useful to add export all packages from your bundles, so that other bundles can import it. To do this, go to the Runtime tab of the MANIFEST.MF editor and add the packages to the Exported-Packages list. Additionally, it is good practice to maintain a version number (e.g. 1.0.0) for each package.

Now that you've created your bundle, you can add your components as you like but do not forget to add a test bundle.

Add bundle to launch configuraton

To add your new bundle to the SMILA launch configuration in the workspace, so that you can test and debug it in a running SMILA system:

  • Open Run -> Run Configurations... or Debug Configurations...
  • In the list on the left side, select OSGi Framework -> SMILA
  • In the Bundles list on the right side, look for your bundle and select it. Defaults for Start level and Auto-Start are OK for pipelet bundles. For bundles containing OSGi services (e.g. workers or HTTP handlers) set Auto-Start to true so that the service gets activated at system start.

Create a Working Set

You may want to create a working set for your own bundles to make it easier to find them among all those SMILA bundles:

  • In the Package Explorer view on the left side, open the menu (click on the small triangle in the upper right corner) and select Select Working Sets...
  • In the following dialog, click New...
    • Select Java, click Next >
    • Enter a name (e.g. "My Bundles"), select you bundle in the left list and click Add -->, then click Finish
  • Select the created working set in the list and click OK

Now only your own bundle will be displayed in the Package Explorer. To view all bundles again, open the explorer view menu again and choose Deselect Working Set. To add more bundles to an existing working set, choose Edit active working set when one is selected. You can also create more working sets (e.g. for subsets of SMILA you need to see) as you like. Just try it out (:

Integrating the new bundle in the build process

To include the just created bundle in the build you should follow the instructions on how to integrate a new bundle into the build process.