p2, 10 common pitfalls and how to avoid them

1. p2, your savior
or your Achilles
heel?
Everything an
Eclipse team
needs to know
about p2!
R. Ian Bull
Pascal Rapicault

2. 2 3/21/2011
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. 3 3/21/2011
#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

4. 4 3/21/2011
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

5. 5 3/21/2011
#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  )

6. 6 3/21/2011
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

7. 7 3/21/2011
#3
Replace published content
 Neverpublish 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.

8. 8 3/21/2011
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

9. 9 3/21/2011
Reuse:
Tips and Tricks
 Context repositories
build.properties:
repoBaseLocation=${buildDirectory}/inputRepositories
transformedRepoLocation=${buildDirectory}/transformedRepo
 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.eclips
e.pde.doc.user/guide/tools/project_wizards/new_featur
e_patch.htm
(or google: eclipse p2 feature patch) 

10. 10 3/21/2011
#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!

11. 11 3/21/2011
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

12. 12 3/21/2011
#5
Don’t categorize things
 p2 only shows what’s been categorized
 Repository designers are responsible for
designing their categories
 Classic consumer / producer problem

13. 13 3/21/2011
Remember:
Category tricks
 Use categories !
 The category publisher is here to help
 Use composite repositories where one of
the repo carry the categories
 Usemeaningful name, and use the
description. The feature name is shorter
than a tweet.

14. 14 3/21/2011
#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

15. 15 3/21/2011
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.

16. 16 3/21/2011
#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

17. 17 3/21/2011
Instead:
Be mindful of what you use
 Look for provisional API (if real API doesn’t
exist)
 Ask on the p2-mailing list

18. 18 3/21/2011
#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

19. 19 3/21/2011
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

20. 20 3/21/2011
#9
Use legacy update sites
 Legacyupdate sites don’t include
complete metadata
 Features are downloaded before any
dependency resolution can occur
 Biglag at install time.
 We will blame you for all p2’s
performance problems 

21. 21 3/21/2011
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.

22. 22 3/21/2011
#10
Spell it P2 
I don’t call your project Mylin, έMF, or BERT

23. 23 3/21/2011
Remember:
The project is:

24. 24 3/21/2011
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