View source for Oomph Targlets

[[File:Oomph_Project_Logo.png|link=Oomph]] <span style="font-size:90%;">[[Oomph|Powered by Oomph]]</span>

Oomph's Targlet technology extends [https://www.eclipse.org/pde/ PDE]'s base functionality for specifying a target platform definition by providing a more expressive, flexible, and reliable mechanism.
The Targlets framework is fully integrated with PDE. 
It uses PDE's target location extension point, providing a Targlet Container implementation to augment PDE's built-in target location implementation.

== Install Targlet Support ==

Use ''Help &rarr; Install New Software...'' and enter one of the [[Oomph#Update_Sites|update sites]], e.g., [http://download.eclipse.org/oomph/updates/milestone http://download.eclipse.org/oomph/updates/milestone], into the "Work with:" combo.
Enter "Oomph Targlets" in the filter, and select the Oomph Targlets feature.

[[File:Oomph_Install_Targlets_Feature.png]]

== Create an Empty Target Definition ==

Use ''Window &rarr; Preferences... &rarr; Plug-in Development &rarr; Target Platform'' to "Add..." a new Target Platform.

[[File:Oomph_PDE_Add_Target_Platform.png]]

Choose "Nothing: Start with an empty target definition" and press "Next".

[[File:Oomph_PDE_Create_Empty_Target_Definition.png]]

Use the "Name:" text field to name it "Sample" and press "Add..." to add a target location.

[[File:Oomph_PDE_Add_Target_Location.png]]

== Add a Targlet Container ==

In the "Add Content" dialog select "Targlet Container" and press "Next".

[[Image:Oomph_Targlet_Add_Targlet_Container.png]]

Use the "Targlet Container ID:" field to enter the name "Sample Targlet Container" and press "Finish".

[[Image:Oomph_Targlet_Add_Targlet_Container_Specify_ID.png]]

Select the new Targlet Container and press "Edit..." to edit it:

[[Image:Oomph_Targlet_Edit_Targlet_Container.png]]

This will save the target definition, dismiss the dialog, and open the Targlet Editor.

== Edit Targlet Container with Targlet Editor ==

The Targlet Editor works well in combination with the Properties view and Oomph's Repository Explorer.
You can open the Properties view from the Targlet Editor's context menu or by double clicking any item in the editor.
You can open the Repository Explorer by entering "Repository Explorer" in the "Quick Access" field to the left of the perspective toolbar in the upper right corner of the perspective.

Double click the root item (only item, currently) in the Targlet Editor and use the context menu to invoke ''New Child &rarr; Targlet''.

[[File:Oomph_Targlet_Editor_New_Child_Targlet.png]]

The new Targlet must have a name.
The editor decorates errors in the tree and in the Properties view.
Use the Properties view to set the "Name" property to "Eclipse SDK".

[[File:Oomph_Targlet_Editor_Set_Targlet_Name.png]]

Use the context menu on the new Targlet named "Eclipse SDK" to invoke ''New Child &rarr; Repository List'' and then use the context menu again to invoke ''New Child &rarr; Repository''.
A Repository must of course specify a URL for a p2 update site.
Use the properties view to enter the URL "http://download.eclipse.org/eclipse/updates/I-builds".
Open the Repository Explorer view and then drag the Repository item and drop it onto the Repository combo in the Repository Explorer.

[[File:Oomph_Targlet_Editor_Drag_Repository_To_Repository_Explorer.png]]

The Repository Explorer will load the p2 repository and display its contents, much like what you're familiar from using the ''Help &rarr; Install New Software...'' dialog.

[[File:Oomph_Targlet_Editor_Use_Repository_Explorer.png]]

For each item you select, you can see which Versions of that item are available in the p2 repository.
You can alter how the Versions are displayed using the controls in the bottom right.
Here "Compatible" is checked, and "Minor" is selected.
You can drag any item, including the Version items, to the "Eclipse SDK" Targlet to create a Requirement.
When dragging a Version item, the version range of the Requirement that's created in the Targlet will reflect the display settings you've chosen.
Here is the result of dragging the "4.8.x" version item to the "Eclipse SDK" Target with the new Requirement selected to display its properties in the Properties view:

[[File:Oomph_Targlet_Editor_New_Requirement_From_Repository_Explorer_Version_Item.png]]

It is significant to note some the difference between editing a Targlet Container with Oomph's Targlet Editor versus editing a *.target file PDE's Target editor.
At this point, we have not downloaded any artifacts from the p2 repository, we've only explored the content metadata and we could author the the complete definition based on just that information.
Also, editing PDE's Software Site container is achieved by specifying so-call installable units, either with an exact version or with the so called omni-version,
but Targlets use Requirements that can specify version ranges, and properties such as optional and greedy, exactly like what you're able to express in a plug-in' MANIFEST.MF.
Requirements are a more expressive mechanism for expressing dependencies for the target platform.

When you save the Targlet Editor's contents, the Targlet Container will resolve in the background.
You can use ''Window &rarr; Preferences &rarr; Plug-in Development &rarr; Target Platform'' to make the "Sample" target platform the active target platform.

== Using a Source Locator ==

Suppose some of your project in the workspace still have dependencies that aren't satisfied.

[[File:Oomph_Targlets_Unresolved_Dependency.png]]

You can of course hunt for them in the Repository Explorer, assuming you know in which p2 repo to find them.
If you don't know the p2 repository, but you expect it's in some repository hosted by Eclipse, you can use [[Eclipse_Oomph_Authoring#How_to_find_a_P2_repository_at_Eclipse_using_the_Repository_Explorer|Eclipse Repository Search]] to find the p2 repository.
Once you know the repository, can you of course browse the contents and use drag and drop to create the necessary Requirements and to add the necessary Repository to a Repository List.

But Oomph's Targlet framework supports another powerful mechanism, namely Source Locators.
The basic concept is that the underlying p2 framework is able to publish p2 metadata from source projects.
PDE's implementation reuses this to build a representation of the plug-ins and features in the workspace.
Oomph's Targlet framework reuses the same technology to induce a logical p2 repository from projects in the file system.
For example, you can use the Repository Explore to browse all your workspace projects as a logical p2 repository.
Select "platform:/resource/" in the Repository Explorer's URL combo.

[[File:Oomph_Targlets_Use_Repository_Explorer_Workspace_Repository.png]]

To exploit this feature, use the Targlet Editor to create another Targlet named "Workspace Dependencies",
create a Requirement in that new Targlet and use the Properties view to change the "Name" to "*";
this is a so-called wildcard requirements.
Then create a Source Locator in that new Target and use the Properties view to set the "Root Folder" to "platform:/resource/".
The result looks like this:

[[File:Oomph_Targlet_Editor_With_Source_Locator.png]]

Assuming you've made the "Sample" target definition the active definition from the previous steps in this tutorial,
saving the Targlet Editor will resolve the target platform,
taking into account the dependencies of all projects in your workspace.
Because the Platform's I-builds include, the "org.junit" bundle,
after the resolution, the workspace error is eliminated because the target platform will contain the required bundle.

This is just a simple though useful example of using a Source Locator.
It should be evident that authoring a target platform in this manner is significantly simpler because you need not replicate/repeat in the target platform definition, the dependencies already expressed in your projects.
Another highly useful aspect not illustrated by this simple example is that you can use a Source Locator to point at a Git clone in your local file system.
During resolution, not only will all the requirements of the projects in that Git clone be resolved,
the projects themselves will be imported into the workspace!