Skip to content

Latest commit

 

History

History
231 lines (154 loc) · 11.9 KB

target_platforms_for_consumers.adoc

File metadata and controls

231 lines (154 loc) · 11.9 KB
Raw

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' target platform update sites are located here, in both unpacked and packed (zipped) format. They do not contain sources or SDK features.

Exploring the JBoss Tools target platform repository

Inside the JBoss Tools Target Platform repository, the two top level folders are jbdevstudio and jbosstools. 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.41 (Luna SR1) or 4.50 (Mars R).

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.42.0, 4.42.1, 4.42.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 (Alpha1, Alpha2, Beta1, Beta2, CR1, 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 Mars, use a 4.50.x target platform. If building for Luna SR1 or SR2, use a 4.41.x or 4.42.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.50.0.Beta1-SNAPSHOT

Using 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

But…​

  • Zips do not contain sources

  • Browse to http://download.jboss.org/jbosstools/targetplatforms/jbosstoolstarget/

  • Select the folder for the version you want such as 4.41.1.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.

  • Can fetch source bundles so you can trace into the source of dependencies

But…​

  • May take in excess of an hour each time

  • Must be done once per workspace

  • Eclipse will cache bundles in hard-to-find locations

  • If your workspace gets corrupted often, this will be time consuming

  • Eclipse resolution may be a bit slower than building a target platform site on the command line

  • Blocks Eclipse, during which time you can’t use it for other work

  • Check out the target platform branch matching the version of Eclipse you need. For a target platform containing Eclipse 4.5.0, check out the 4.50.x branch.

git clone https://github.com/jbosstools/jbosstools-target-platforms.git
cd jbosstools-target-platforms
git checkout 4.50.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

But…​

  • More complicated

  • Check out the target platform branch matching the version of Eclipse you need. For a target platform containing Eclipse 4.5.0, check out the 4.50.x branch.

git clone https://github.com/jbosstools/jbosstools-target-platforms.git
cd jbosstools-target-platforms
git checkout 4.50.x

  • If you do not require source bundles, you should then type:

mvn clean install -Pmultiple2repo

  • If you DO require source bundles, you should then type:

mvn clean install -Pmultiple2repo -Dmirror-target-to-repo.includeSources=true

  • 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

Installing 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:

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.

Using a target platform in a maven build

JBoss Tools modules use Maven to build and are configured to consume the latest target platform from Nexus, based on what’s set in the parent pom.

If you want to use a newer version, simply build with mvn verify -Dtpc.version=4.42.1.Final.