target_platforms_for_consumers.adoc

Using target platforms

This document explains how to consume target platforms in Eclipse.

What is a target platform?

A target platform, in abstract terms, is a set of external dependencies that your features, plugins, and tests will use and on which their development and installation will depend. For JBoss Tools, these dependencies come from various Eclipse.org projects and other providers. Our target platforms can be used inside Eclipse to:

• provide the right set of dependencies with which to debug, test, and develop;

• provide the right set of dependencies at build time; and

• provide a site containing all dependencies to end-users at install time.

In concrete terms, a target platform can take two forms: a target platform definition file and a target platform update site.

A target platform definition file is a custom Eclipse file, with a .target suffix, for use by Eclipse’s Plug-in Development Environment (PDE) tools. The file lists the versions of installable units (IUs) to be used as dependencies, as well as the repositories from which those dependencies can be found. The contained IUs are generally features, but can also be invididual plugins.

A target platform update site is the result of resolving the target platform definition file, which is the process of downloading all the IUs, and thier contained IUs, to one’s local disk. It includes the full set of jars for all dependencies our project may depend on, as well as the required Eclipse metadata to act as an update site. An update site, in Eclipse, is a mechanism used to install new (or update existing) software into Eclipse. Because of this, you could probably install the entire target platform into your Eclipse using such an update site.

See these slides for more about target platforms: http://www.slideshare.net/mickaelistria/a-journey-with-target-platforms.

Where is the target platform for JBoss Tools?

JBoss Tools' target platform definition files are stored in github:

• JBoss Tools & Red Hat CodeReady Studio Target Platforms

• JBoss Tools Central Target Platforms

• Integration Stack Target Platforms

JBoss Tools' target platform update sites are located here, in both unpacked and packed (zipped) format. They do not contain sources or SDK features.

• http://download.jboss.org/jbosstools/targetplatforms/ (SNAPSHOTS, milestones, and links to released versions)

Exploring the JBoss Tools target platform repository

Inside the JBoss Tools Target Platform repository, there is one top level folders, jbosstools (there used to be a separate target platform for devstudio but that’s since been merged with the jbosstools one). Both of these folders contain two sub-folders: multiple and unified.

Multiple vs unified target platforms

Multiple target platform definition files reference several different update sites, most of which are mirrors located on http://download.jboss.org/jbosstools/. Use this .target file in Eclipse, since it can include sources when built with the proper flags.

Unified target platform definition files are generated from the multiple ones, and are then used to produce the target platform update sites. As this file references only a single mirror, it is faster to use in Eclipse but cannot include sources, since it points at the generated target platform update site, which does not include sources. If you are a developer or adopter, do not choose this definition file - it should only used by end-users at installation time.

Versioning rules

JBoss Tools uses a well-defined versioning scheme for our target platforms.

The first 3 digits are the version of Eclipse included in the target platform, such as 4.80 (Photon.0).

The next digit signifies the sequence of target platforms, starting with 0. Should there be multiple JBoss Tools releases on the same Eclipse version, this allows us to have different target platforms using the same baseline, such as 4.80.0, 4.80.1, 4.80.2.

After that, the milestone of JBoss Tools that uses the target platform is suffixed, which also defines the quality/stability of the target platform (AM1, AM2, AM3, Final).

Finally, the target platform version will have a -SNAPSHOT suffix if it has not yet been released to Nexus. Once released, the -SNAPSHOT suffix is removed. For .Final versions, the bits are moved to mirrored to the Akamai /static/ folder for better performance.

Choosing the appropriate target platform

Normally, each project uses a parent pom that will default to the right target platform, but in case you need to update to, or test against, a different target platform, this section will be useful for you.

In general, we use the latest target platform for the version of Eclipse your development environment requires. For example, if you are building code for Photon, use a 4.80.x target platform.

If you use the latest parent pom, chances are good you’ll automatically build with the latest appropriate target platform too.

However, this will default to use the latest minimum target platform based on the initial R release of the annual Eclipse release train, not the SR1 or SR2 updates. To quickly switch to building with the latest maximum target platform (eg., the SR2 version), use this profile:

mvn install -P maximum

Should you want to build using a specific target platform, perhaps because you’re testing a new, unreleased one, you could build like this:

mvn install -Dtpc.version=4.80.0.AM1-SNAPSHOT

Using a locally-built target platform

If you built a target platform locally from the sources in 4.80.x target platform, you can reference that unified target platform from within your .m2 repo.

mvn install -Dtpc.version=4.80.0.AM1-SNAPSHOT

Using a locally-downloaded target platform

But if you downloaded the target platform as a zip, and want to use that instead, you’ll need to use a couple more commandline properties. First, download and unpack the target platform zip.

Then add this to your root pom:

  <profiles>
    <profile>
      <id>target-site</id>
      <activation>
        <property>
          <name>jbosstools-target-site</name>
        </property>
      </activation>
      <repositories>
        <repository>
          <id>jbosstools-target-site</id>
          <layout>p2</layout>
          <url>${jbosstools-target-site}</url>
        </repository>
      </repositories>
    </profile>
  <profiles>

Now you can build using the target platform update site, rather than the target platform definition:

mvn clean install -Dno-target-platform \
  -Djbosstools-target-site=file:///path/to/where/you/unzipped/jbosstoolstarget/4.80.0.AM1-SNAPSHOT/jbosstoolstarget-4.80.0.AM1-SNAPSHOT.zip/

How can I use a target platform in Eclipse?

There are several different options you can use when attempting to configure your Eclipse workspace with a target platform. Each method has its own advantages and disadvantages.

Method	Advantages/Disadvantages	Steps
Import target platform zip	Fast Requires very little setup Do not need to check out jbosstools-target-platforms Easily reused for an unlimited number of workspaces As of 4.80, both jbosstools & devstudio target platforms include sources and testing dependencies. With source bundles, so you can trace into dependencies' sources	Browse to jbosstoolstarget or devstudiotarget Select the folder for the version you want such as 4.80.0.Final Select the zip file and save it to disk Unzip it to a location you desire Inside Eclipse, browse to Window → Preferences → Target Platform and click Add…​ Click Next> On the locations tab, click Add…​ Select Directory and click Next> Browse to your unzipped target platform folder Click Finish, and Finish again. Check your new target platform and watch it load very quickly
Import .target file	By far the easiest method. With source bundles, so you can trace into dependencies' sources But…​ May take in excess of an hour each time, usually blocking the workspace. (see EBZ 507397 for potential improvement) Must be done once per workspace (see EBZ 282352 ) If your workspace gets corrupted often, this will be time consuming Eclipse will cache bundles in ${workspace}/.metadata/.plugins/ org.eclipse.pde.core/.bundle_pool (see EBZ 282352 )	Check out the target platform branch matching the version of Eclipse you need. For a target platform containing Eclipse 4.8.0 (Photon.0), check out the 4.80.x branch. git clone https://github.com/jbosstools/jbosstools-target-platforms.git cd jbosstools-target-platforms git checkout 4.80.x Next, import the jbosstools/multiple project into Eclipse. This project must be imported as a maven project. To import this project, select File → Import → Existing Maven Project and browse to the jbosstools/multiple project location. When done, go to Window → Preference → Plug-in Development → Target Platforms, select the recent multiple.target entry which should be visible in the preference page, and click Apply (or Reload in case of updates only). Note Rather than importing, you can simply open a .target file with the Target Definition editor. In the top-right corner, click the Export button and select a destination directory. If you selected a .target file with source references, such as jbosstools-multiple.target, you will also resolve sources - convenient for development work. Beware, in both cases this is a long operation that can take up to an hour, depending on your internet connection, during which time Eclipse can’t be used for anything else.
Build target platform	Fast Flexible Can include sources Easily reused for an unlimited number of workspaces With source bundles, so you can trace into dependencies' sources But…​ More complicated	Check out the target platform branch matching the version of Eclipse you need. For a target platform containing Eclipse 4.8.0, check out the 4.80.x branch. git clone https://github.com/jbosstools/jbosstools-target-platforms.git cd jbosstools-target-platforms git checkout 4.80.x If you require source bundles, you should type: mvn install -f jbosstools/multiple/pom.xml -Pmultiple2repo If you do NOT require source bundles, you should type: mvn clean install -f jbosstools/multiple/pom.xml -Pmultiple2repo -Dmirror-target-to-repo.includeSources=false Both of the above builds are long-running, and may take upwards of an hour. Next: Inside Eclipse, browse to Window → Preferences → Target Platform and click Add…​ Click Next> On the locations tab, click Add…​ Select Directory and click Next> Browse to `jbosstools-target-platforms/jbosstools/multiple/target/jbosstools-multiple.target.repo/plugins Click Finish, and Finish again. Check your new target platform and watch it load very quickly

How can I install the contents of a target platform into Eclipse?

Up until this point, we’ve only been referencing using a target platform in eclipse to resolve dependencies. When simply using a target platform, it is not 'installed' into your eclipse, but rather all the units are stored locally and then resolved and referenced for compilation and run-time resolution.

Under some circumstances, users may wish to actually install the target platform (or some subset of it) into their running eclipse installation. This is very useful when testing local builds, for example.

With this in mind, if you have a local copy of the target platform unzipped on your disk, or if you wish to simply install from our web urls, you can perform the following to install it into your actual eclipse application:

• Select Window → Install New Software

• Click Add…​

• Provide a name

• Browse to the location of your local target platform, or paste a target platform URL such as http://download.jboss.org/jbosstools/targetplatforms/jbosstoolstarget/4.80.0.Final/

• Uncheck Group item by category

• Click Select All

• Click Next> and continue until you can Finish

• Install all of the items.

If this is a task you intend to perform often, you will find it very useful to have a local target platform folder, rather than continuously download and install from a remote location.

After installing the target platform, you should restart your eclipse. You will find you have all dependencies locally installed and running, rather than being used only for plug-in dependency resolution.

How can I resolve target platform sources in Eclipse?

If the target platform site is available from Window → Preferences → Install/Update → Available Software Sites, you can use the PDE Source Lookup plugin to automatically fetch missing source bundles and make them available for development.

See Using the PDE Source Lookup plugin for more how to install and use this plugin.