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.

3/21/2011 2

#1

Move / 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

3/21/2011 3

Instead:

Let p2 manage your install Other 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

3/21/2011 4

#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 )

3/21/2011 5

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

3/21/2011 6

#3

Replace 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.

3/21/2011 7

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

3/21/2011 8

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)

3/21/2011 9

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!

3/21/2011 10

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 SDK http://wiki.eclipse.org/Eclipse_Project_Update_Sites

3/21/2011 11

#5

Don’t categorize things

p2 only shows what’s been categorized

Repository designers are responsible for

designing their categories

Classic consumer / producer problem

3/21/2011 12

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.

3/21/2011 13

#6

Ignore 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

3/21/2011 14

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.

3/21/2011 15

#7

Don’t USE API If you find yourself reaching into internals,

ask yourself why?

If you manually write to the bundles.info file, 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

3/21/2011 16

Instead:

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

exist)

Ask on the p2-mailing list

3/21/2011 17

#8 Use the Metadata generator

If you are using the Metadata generator… sorry

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

Deprecated two years ago

Removed for Indigo

3/21/2011 18

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

3/21/2011 19

#9 Use 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

3/21/2011 20

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.

3/21/2011 21

#10 Spell it P2

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

3/21/2011 22

Remember:

The project is:

3/21/2011 23

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

3/21/2011 24