p2, your savior

or your Achilles

heel?

Everything an

Eclipse team

needs to know

about p2!

R. Ian Bull

Pascal Rapicault

Alternate Titles

10 reasons we closed your p2 bugs as INVALID?

10 ways to get booted from the p2 mailing list!

10 excuses why we didn’t buy you a beer

p2, 10 common pitfalls and how to avoid them.

4/11/20112

#1Move / remove files on disk

Leading cause of p2 failures:

developers tampering with plugins/ folder

If you no longer need a plugin DO NOT

REMOVE IT BY HAND

Do not move, unzip or change a plug-in in

your plugins/ directory

4/11/20113

Instead:

Let p2 manage your installOther plug-ins may depend on it

If a plug-in is no longer needed, p2 will

remove it

Run the Garbage Collector manually if you

want

# ./eclipse –application \

org.eclipse.equinox.p2.garbagecollector.application

4/11/20114

#2 Unzip your plug-ins over Eclipse

Do you provide a zip file for your plugins?

Do you instruct your users to unzip over

eclipse

We don’t like you! (And we will sabotage your wiki page )

4/11/20115

Instead:

Provide a repository Repositories can be zipped and

downloaded!

Users can simply point to the compressed

repository to properly install your plug-in

Avoid the use of drop-ins too

4/11/20116

#3Replace published content

Never publish different content with the

same version number!

Do not make a change and use the same

version number

Do not build plug-ins as Foo v1.0.0.HEAD

You’ll never know what your user runs.

4/11/20117

Remember:

Version / ID pairs are immutable

If the Version / ID has not changed, the content hasn’t changed!

Always publish new metadata and artifacts for each code change

Use .qualifiers for all bundles / plug-ins and features

If you can’t rebuild everything, provide patches to deliver surgical updates

4/11/20118

Reuse:

Tips and Tricks Context repositories

Qualifier replacement / bundle reuse forceContextQualifier: Replaces the qualifier of all

your bundles (use build timestamp)

Feature patches:http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/project_wizards/new_feature_patch.htm(or google: eclipse p2 feature patch)

4/11/20119

build.properties:repoBaseLocation=${buildDirectory}/inputRepositories

transformedRepoLocation=${buildDirectory}/transformedRepo

#4 Alter a released repository

“Release” repositories are serious stuffs!

People will refer to them from their repo to

avoid duplicating your content

People will refer to them from their build

Removing content from a “release” repo

is a felony!

4/11/201110

Instead:

Be mindful of your users / repos Preserve content at the same URL

If you put out bad bytes, publish a new version. Don’t remove the old one !

Append new version to existing repo.

Disk is cheap, users not patient (and they’ll blame p2).

For this, use p2 composite repositories.

Define clear retention policies

For example, the policies for the SDKhttp://wiki.eclipse.org/Eclipse_Project_Update_Sites

4/11/201111

#5Don’t categorize things

p2 only shows what’s been categorized

Repository designers are responsible for

designing their categories

Classic consumer / producer problem

4/11/201112

Remember:

Category tricks Use categories !

The category publisher is here to help

Use composite repositories where one of

the repo carry the categories

Use meaningful name, and use the

description. The feature name is shorter

than a tweet.

4/11/201113

#6Ignore your version ranges

Specify a strict dependency on 3.6.1 and

wonder why your users can’t install on

3.6.2?

Most illegible p2 error messages are a result

of poorly set version ranges

4/11/201114

Instead:

Consider your version ranges

Version your packages, bundles and

features

Use version ranges for dependencies:

Up-to by not including [3.6.0, 3.7.0)

Unbounded lower [0.0.0, 3.7.0)

Unbounded higher 2.0

Strict Versions [3.6.1, 3.6.1]

You need to know what the producer does.

4/11/201115

#7Don’t USE API If you find yourself reaching into

internals, ask yourself why?

If you manually write to the bundles.infofile, ask yourself why?

If you edit content.xml / artifacts.xml by hand, ask yourself why?

Two problems when you don’t use API:

We could break you

You could break you

4/11/201116

Instead:

Be mindful of what you use Look for provisional API (if real API doesn’t

exist)

Ask on the p2-mailing list

4/11/201117

#8Use the Metadata generator

If you are using the Metadata generator… sorry

(org.eclipse.equinox.p2.metadata.generator)

Deprecated two years ago

Removed for Indigo

4/11/201118

Instead:

Use the Publisher Publisher Applications & Ant Tasks

Publish from an Update Site

Publish from Features / Bundles

Publish from a Product

Publish categories

# ./eclipse -application

org.eclipse.equinox.p2.publisher.UpdateSitePublisher

-metadataRepository file:///repo

-artifactRepository file:///repo

-source http://foo/site.xml-compress

-publishArtifacts

4/11/201119

#9Use legacy update sites

Legacy update sites don’t include

complete metadata

Features are downloaded before any

dependency resolution can occur

Big lag at install time.

We will blame you for all p2’s performance problems

4/11/201120

Instead:

Use a real build tool PDE Build, Tycho and derivatives

(Athena, Buckminster, etc.) all provide

facilities to build p2 repositories.

If you can’t change your build

technology, at lease use the Update Site

Publisher.

4/11/201121

#10Spell it P2

I don’t call your project Mylin, έMF, or BERT

4/11/201122

Remember:

The project is:

4/11/201123

Useful links http://wiki.eclipse.org/Equinox_p2

http://wiki.eclipse.org/Equinox/p2/Getting_Started

http://wiki.eclipse.org/Equinox/p2/Publisher

http://aniefer.blogspot.com/2008/06/example-

headless-build-for-rcp-product.html

4/11/201124