Using p2 for fun and profit Pascal Rapicault* Ian Bull** Andrew Niefer* Jeff McAffer** * IBM Rational ** EclipseSource

Provision what – where Engineers Users Test Automated Builds Test source code open source licensed software in-house built applications tools runtimes

Packaged applications – source code Strict policy control – full flexibility Approved repositories – any repository Fixed configuration – dynamic configuration Fully automatic – user driven – (headless) U pdate to latest – update to policy controlled (downgrade) Wide range of requirements

Packaged applications – source code

Strict policy control – full flexibility

Approved repositories – any repository

Fixed configuration – dynamic configuration

Fully automatic – user driven – (headless)

U pdate to latest – update to policy controlled (downgrade)

An extensible provisioning platform Install and update technology in the SDK since 3.4 New UI, simplified workflow Manage Eclipse, RCP and more exe, ini, bundles, registry keys, native code, … Shared bundles across Eclipse-based products A provisioning solution for OSGi™ systems Managing non-running instance Start level, framework extension Fine-grained dependency management p2 is about installing!

An extensible provisioning platform

Install and update technology in the SDK since 3.4

New UI, simplified workflow

Manage Eclipse, RCP and more

exe, ini, bundles, registry keys, native code, …

Shared bundles across Eclipse-based products

A provisioning solution for OSGi™ systems

Managing non-running instance

Start level, framework extension

Fine-grained dependency management

Eclipse proves the power of componentization Componentization naturally spreads More components -> more management Management is hard It’s all about the Contract Defining Instantiating Executing Maintaining Trends in Eclipse

Eclipse proves the power of componentization

Componentization naturally spreads

More components -> more management

Management is hard

It’s all about the Contract

Defining

Instantiating

Executing

Maintaining

How does p2 help? Manages the contract Dependencies Code Settings Integrations Non-Eclipse parts Extensible GUI and Headless One consistent model

Manages the contract

Dependencies

Code

Settings

Integrations

Non-Eclipse parts

Extensible

GUI and Headless

One consistent model

From Install to Service Installing and Updating are the same operations Installed shape same as zip shape Flexibility in delivery Programmatic API for all operations p2 offers a continuum from initial installation to serviceability

Installing and Updating are the same operations

Installed shape same as zip shape

Flexibility in delivery

Programmatic API for all operations

p2 in wild Installer for products (EPP Wizard, WindRiver, Motorola, IBM Rational, etc.) Server managed deployment solution and distros (Genuitec, EclipseSource) Remote management of device (EclipseSource) Dynamic builder – Buckminster (Cloudsmith) Provisioning of server side (EclipseSource) Cloud provisioning (EclipseSource)

Installer for products (EPP Wizard, WindRiver, Motorola, IBM Rational, etc.)

Server managed deployment solution and distros (Genuitec, EclipseSource)

Remote management of device (EclipseSource)

Dynamic builder – Buckminster (Cloudsmith)

Provisioning of server side (EclipseSource)

Cloud provisioning (EclipseSource)

Outline p2 by example Integrating p2 in a feature based RCP application p2 concepts and architecture Layout of our application on disk and additional p2 concepts Creating and delivering an update Creating and delivering an extension Automated build and repo management Repo management Metadata publication (source and product) Categorizing content Deeper in p2 Additional p2 constructs From plug-ins and feaures to metadata Plug-ins map Reusing and tweaking the UI Advanced concepts

p2 by example

Integrating p2 in a feature based RCP application

p2 concepts and architecture

Layout of our application on disk and additional p2 concepts

Creating and delivering an update

Creating and delivering an extension

Automated build and repo management

Repo management

Metadata publication (source and product)

Categorizing content

Deeper in p2

Additional p2 constructs

From plug-ins and feaures to metadata

Plug-ins map

Reusing and tweaking the UI

Advanced concepts

p2 by example Integrating p2 in a feature based RCP application p2 concepts and architecture Layout of our application on disk and additional p2 concepts Creating and delivering an update Creating and delivering an extension Build and repo management Deeper in p2

p2 by example

Integrating p2 in a feature based RCP application

p2 concepts and architecture

Layout of our application on disk and additional p2 concepts

Creating and delivering an update

Creating and delivering an extension

Build and repo management

Deeper in p2

What is RCP? Rich Client Platform The minimal set of plug-ins needed to build a Rich Client Application Clients are free to use other plug-ins Help p2 GEF / Draw2D Birt … Integrate p2 in an RCP Application Publish the application to a repository Install the application using p2 Update an existing install Add new functionality to the RCP application

Rich Client Platform

The minimal set of plug-ins needed to build a Rich Client Application

Clients are free to use other plug-ins

Help

p2

GEF / Draw2D

Birt

…

Integrate p2 in an RCP Application

Publish the application to a repository

Install the application using p2

Update an existing install

Add new functionality to the RCP application

What is a Product? An application-specific branding on top of a configuration of Eclipse plug-ins Application icon Splash screen Help -> About information Platform specific launcher

An application-specific branding on top of a configuration of Eclipse plug-ins

Application icon

Splash screen

Help -> About information

Platform specific launcher

Creating a feature based product Integrate p2 in an RCP Application Publish the application to a repository Install the application using p2 Update an existing install Add new functionality to the RCP application In the following example we are using a feature based product. However plug-in based product is supported Create a Bundle for y our mail application Every bundle needs a name and version with a qualifier Let's call ours: org.example.mail

Integrate p2 in an RCP Application

Publish the application to a repository

Install the application using p2

Update an existing install

Add new functionality to the RCP application

In the following example we are using a feature based product. However plug-in based product is supported

Create a Bundle for y our mail application

Every bundle needs a name and version with a qualifier

Let's call ours: org.example.mail

Creating a feature based product Integrate p2 in an RCP Application Publish the application to a repository Install the application using p2 Update an existing install Add new functionality to the RCP application Every bundle needs a name and version with a qualifier Of course we want a Rich Client Application

Integrate p2 in an RCP Application

Publish the application to a repository

Install the application using p2

Update an existing install

Add new functionality to the RCP application

Every bundle needs a name

and version with a qualifier

Of course we want a

Rich Client Application

Creating a feature based product PDE contains all sorts of examples, templates and documentation

PDE contains all sorts of examples, templates and documentation

Creating a feature for our plug-in Features have a name and version too Let's create a Feature

Features have a name and version too

Let's create a Feature

A feature for the p2 parts In order to keep things separated in the application, we create a feature that contains the p2 plug-ins we need. For this example, it does not include the support for legacy sites nor drop-ins.

In order to keep things separated in the application, we create a feature that contains the p2 plug-ins we need.

For this example, it does not include the support for legacy sites nor drop-ins.

Creating the product file Let's create a Product Let's base our product off features On the dependencies tab we add the features that constitute the product

Let's create a Product

Let's base our

product off features

On the dependencies tab we add the features that constitute the product

Launching the product (from within eclipse)

The running product In self-hosting mode, the application being launched is not p2-enabled, as such the p2 dialogs can not be brought up. We can only update if we have a profile. This problem will unlikely be addressed in 3.5.

Publishing the application to a repository

The result of the export The export produced the application in a runnable form and also repositories. The application in a runnable form is *not* p2-enabled and will fail to open the p2 dialogs. This should be fixed for 3.5. Notice the file extensions on the artifacts and content file! What's in these JAR files? p2 repositories.

The export produced the application in a runnable form and also repositories.

The application in a runnable form is *not* p2-enabled and will fail to open the p2 dialogs. This should be fixed for 3.5.

Notice the file extensions on the artifacts and content file! What's in these JAR files? p2 repositories.

p2 by example Integrating p2 in a feature based RCP application p2 concepts and architecture Layout of our application on disk and additional p2 concepts Creating and delivering an update Creating and delivering an extension Build and repo management Deeper in p2

p2 by example

Integrating p2 in a feature based RCP application

p2 concepts and architecture

Layout of our application on disk and additional p2 concepts

Creating and delivering an update

Creating and delivering an extension

Build and repo management

Deeper in p2

One construct to rule them all Decouple decision making from the actual content Everything is an IU Everything is installable It is also referred to as “metadata” IU (id, ver)

Anatomy of an IU Provided Capabilities Required Capabilities Properties Artifact reference Actions Class: IInstallableUnit IU (id, ver)

Anatomy of an IU, more Update description This allows to control of which IU and IU is an update of Applicability filter This allows for an IU to express when it is only applicable to a particular environment.

Update description

This allows to control of which IU and IU is an update of

Applicability filter

This allows for an IU to express when it is only applicable to a particular environment.

Anatomy of an IU, requirements / capabilities Capabilities and requirements are the mechanism by which an IU express what it provides and what needs. A capability is composed of a: Namespace (string), name (string) and version A requirement is composed of a: Namespace, name and version range Namespace, name and version are open ended. The requirements and capabilities expressed by IUs can be arbitrary and don’t have to all be in the same namespace. Resources – RPMs, .exes, docs, … Virtual – if you can define a capability, I can depend on it

Capabilities and requirements are the mechanism by which an IU express what it provides and what needs.

A capability is composed of a:

Namespace (string), name (string) and version

A requirement is composed of a:

Namespace, name and version range

Namespace, name and version are open ended.

The requirements and capabilities expressed by IUs can be arbitrary and don’t have to all be in the same namespace.

Resources – RPMs, .exes, docs, …

Virtual – if you can define a capability, I can depend on it

Separation of concerns Installable Unit Exists independently of the repository Metadata Repository Store only Installable Units Artifact Repository Store only Artifacts Metadata Artifacts

Installable Unit

Exists independently of the repository

Metadata Repository

Store only Installable Units

Artifact Repository

Store only Artifacts

Artifacts Bytes/content to be installed Any form JARs (e.g., bundles, features, …)‏ Binary executables RPM, MSI, … Defined, maintained, loaded and used separately from the metadata

Bytes/content to be installed

Any form

JARs (e.g., bundles, features, …)‏

Binary executables

RPM, MSI, …

Defined, maintained, loaded and used separately from the metadata

Repositories p2 does not force a serialization format for repositories Defined as an interface, IRepository All repositories have Identity Version Description Repos can be queried Allows for delayed loading Captures standard questions

p2 does not force a serialization format for repositories

Defined as an interface, IRepository

All repositories have

Identity

Version

Description

Repos can be queried

Allows for delayed loading

Captures standard questions

Metadata Repository Defined as an interface, IMetadataRepository Add/remove installable units Add references to other repos Created by factories Looked up in an IMetadataRepositoryManager service

Defined as an interface, IMetadataRepository

Add/remove installable units

Add references to other repos

Created by factories

Looked up in an IMetadataRepositoryManager service

Built-in metadata repositories URL and Local based Simple XML format on disk ( content.jar / content.xml ) Write (re)writes the entire structure Update site repo site.xml and features are auto-published into local repo Bundle IUs published as partial IUs and filled in on demand

URL and Local based

Simple XML format on disk ( content.jar / content.xml )

Write (re)writes the entire structure

Update site repo

site.xml and features are auto-published into local repo

Bundle IUs published as partial IUs and filled in on demand

Artifact Repository Defined as an interface, IArtifactRepository Add/remove descriptors Test content Access artifacts by descriptor Created by factories Looked up in an IArtifactRepositoryManager service

Defined as an interface, IArtifactRepository

Add/remove descriptors

Test content

Access artifacts by descriptor

Created by factories

Looked up in an IArtifactRepositoryManager service

Artifact Repository An artifact can be stored in multiple forms IArtifactKey, is the artifact identifier independently of its form A key is made of: Classifier, name, version The key is what an installable unit refers to IArtifactDescriptor identifies actual content in a particular form Location of actual artifact (can be independent of repository location) Processing steps necessary to recreate the artifact in the expected form (e.g. unpack for pack200’ed jars) Download size, on-disk size, MD5, etc..

An artifact can be stored in multiple forms

IArtifactKey, is the artifact identifier independently of its form

A key is made of: Classifier, name, version

The key is what an installable unit refers to

IArtifactDescriptor identifies actual content in a particular form

Location of actual artifact (can be independent of repository location)

Processing steps necessary to recreate the artifact in the expected form (e.g. unpack for pack200’ed jars)

Download size, on-disk size, MD5, etc..

Id + version == unique content For artifacts and IUs: Id + version == unique content Failing this could result in problems: [1] Your user does not run the content it should MD5 or signature verification error at install time PDE and p2 help avoid these problems with comparison tools [1] Andrew’s short talk.

For artifacts and IUs:

Id + version == unique content

Failing this could result in problems: [1]

Your user does not run the content it should

MD5 or signature verification error at install time

PDE and p2 help avoid these problems with comparison tools

Built-in artifact repositories SimpleArtifactRepository Simple XML format on disk ( artifacts.jar / artifacts.xml ) Write (re)writes the entire structure

SimpleArtifactRepository

Simple XML format on disk ( artifacts.jar / artifacts.xml )

Write (re)writes the entire structure

p2 Architecture Metadata Artifacts Runtimes Profiles OS Eclipse Engine Eclipse Classic Eclipse for C++ Other Director Repositories Touchpoints

The Director Application A command line app to perform basic provisioning operations (install / uninstall) The director is capable of provisioning a complete installation from scratch or simply extending your application Can provision into self or another application http://wiki.eclipse.org/Equinox_p2_director_application

A command line app to perform

basic provisioning operations (install / uninstall)

The director is capable of provisioning a complete installation from scratch or simply extending your application

Can provision into self or another application

Running the director ./eclipse -console -consolelog -application org.eclipse.equinox.p2.director.app.application -metadataRepository file:c:/mail/repository -artifactRepository file:c:/mail/repository -installIU com.example.mail.product -destination c:/mail/tmp/ -profile MailProfile - vmargs -Declipse.p2.data.area=c:/mail/tmp/eclipse/p2

./eclipse

-console -consolelog

-application org.eclipse.equinox.p2.director.app.application

-metadataRepository file:c:/mail/repository

-artifactRepository file:c:/mail/repository

-installIU com.example.mail.product

-destination c:/mail/tmp/ -profile MailProfile

- vmargs -Declipse.p2.data.area=c:/mail/tmp/eclipse/p2

p2 in Action Transports Http/Https File system Volume Director Profiles Runtimes Provisioning operation requested Metadata fetched and constraints analyzed IU install, uninstall, update operations Artifact availability and mirroring Mirroring Data transfer IUs configured into runtimes Profile updated Repositories p2 Update Site Engine Eclipse/OSGi Native/OS

p2 by example Integrating p2 in a feature based RCP application p2 concepts and architecture Layout of our application on disk and additional p2 concepts Creating and delivering an update Creating and delivering an extension Build and repo management Deeper in p2

p2 by example

Integrating p2 in a feature based RCP application

p2 concepts and architecture

Layout of our application on disk and additional p2 concepts

Creating and delivering an update

Creating and delivering an extension

Build and repo management

Deeper in p2

A p2-enabled application Because we installed our product, we have a profile and the p2 dialog can come up

Because we installed our

product, we have a profile and the p2 dialog can come up

What is being run What's our product all about ?

What's our product all about ?

Layout of an installation Configuration area p2 data area Artifact repository index. This allows the plug-ins to be served to other instances.

Configuration data detailed Simple configurator provides the OSGi framework the list of bundles to run. The information stored in bundles.info is Location, id, version, start level, started state Configuration area Simple configurator data

Simple configurator provides the OSGi framework the list of bundles to run.

The information stored in bundles.info is

Location, id, version, start level, started state

p2 data area Download cache, where non-eclipse pieces are mirrored before being installed. Profile registry Storage for the profile Lock file created when the profile is being modified Current and previous state of the system MailApp.profile

Profile and profile registry A profile is the complete description in terms of IU of what is installed A profile contains Properties defining the “environment” such as os, ws, arch, install location, bundle pool location The list of IUs Properties associated with each IUs Profiles are held by a profile registry A profile registry can hold on to several profiles Class: *.p2.engine.IProfile, IProfileRegistry

A profile is the complete description in terms of IU of what is installed

A profile contains

Properties defining the “environment” such as os, ws, arch, install location, bundle pool location

The list of IUs

Properties associated with each IUs

Profiles are held by a profile registry

A profile registry can hold on to several profiles

Class: *.p2.engine.IProfile, IProfileRegistry

Management modes and profile registry External mode The p2 plug-ins are external to the application (e.g an installer) Co-hosted mode The p2 plug-ins are in your application (e.g. the Eclipse SDK). This mode still allows the application to be externally managed. For each case, the profile registry (in fact the p2 data area) can be hosted either in the application being managed or in the managing application.

External mode

The p2 plug-ins are external to the application (e.g an installer)

Co-hosted mode

The p2 plug-ins are in your application (e.g. the Eclipse SDK). This mode still allows the application to be externally managed.

For each case, the profile registry (in fact the p2 data area) can be hosted either in the application being managed or in the managing application.

Changing a profile A profile is usually created during the initial installation It is changed by provisioning operations performed using: The director application The API The UI …

A profile is usually created during the initial installation

It is changed by provisioning operations performed using:

The director application

The API

The UI

…

p2 by example Integrating p2 in a feature based RCP application p2 concepts and architecture Layout of our application on disk and additional p2 concepts Creating and delivering an update Creating and delivering an extension Build and repo management Deeper in p2

p2 by example

Integrating p2 in a feature based RCP application

p2 concepts and architecture

Layout of our application on disk and additional p2 concepts

Creating and delivering an update

Creating and delivering an extension

Build and repo management

Deeper in p2

Creating an update Let's make a small change to our product and update the version

Let's make a small change to our product and update the version

Version Numbers p2 relies heavily on version numbers major.minor.service.qualifier Semantics of segment changes Major – Breaking API changes Minor – New API Service – Bug fixes and minor enhancements Qualifier – Build id, source control tag Qualifier is a string Typically source control tag IU versions should be monotonically increasing

p2 relies heavily on version numbers

major.minor.service.qualifier

Semantics of segment changes

Major – Breaking API changes

Minor – New API

Service – Bug fixes and minor enhancements

Qualifier – Build id, source control tag

Qualifier is a string

Typically source control tag

IU versions should be monotonically increasing

Installing the update

Installing the update Note that p2 support dynamic addition or removal of bundles. In this case it is the application that is not dynamic.

Note that p2 support dynamic addition or removal of bundles.

In this case it is the application that is not dynamic.

After the update and restart

p2 by example Integrating p2 in a feature based RCP application p2 concepts and architecture Layout of our application on disk and additional p2 concepts Creating and delivering an update Creating and delivering an extension Build and repo management Deeper in p2

p2 by example

Integrating p2 in a feature based RCP application

p2 concepts and architecture

Layout of our application on disk and additional p2 concepts

Creating and delivering an update

Creating and delivering an extension

Build and repo management

Deeper in p2

Creating a new plug-in to install Don’t forget to specify .qualifier.

Don’t forget to specify .qualifier.

Create a feature to deliver our plug-ins By default p2 UI is not configured to show plug-ins in “ Install new software view ”. You need to use a feature.

By default p2 UI is not configured to show plug-ins in “ Install new software view ”. You need to use a feature.

Exporting the feature How do you create a repository for your exported bundles / features ? You set the option to that effect in the “options” tab.

How do you create a repository for your exported bundles / features ?

You set the option to that effect in the “options” tab.

The publisher The publisher is responsible for creating (publishing) repositories from different types of sources Bundles and Features Publisher UpdateSite Publisher Product Publisher Category Publisher

The publisher is responsible for creating (publishing) repositories from different types of sources

Bundles and Features Publisher

UpdateSite Publisher

Product Publisher

Category Publisher

Features and Bundles Publisher ./eclipse -console -consolelog -application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher -metadataRepository file:c:/mail/repository -artifactRepository file:c:/mail/repository -source c:/staging -append -publishArtifacts This will generate metadata for the plug-ins and features found in source. Note that PDE has an option to do it automatically.

./eclipse

-console -consolelog

-application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher

-metadataRepository file:c:/mail/repository

-artifactRepository file:c:/mail/repository

-source c:/staging

-append

-publishArtifacts

Installing the newly created extension

p2 by example Build and repo management Repo management Metadata publication (source and product) Categorizing content Deeper in p2

p2 by example

Build and repo management

Repo management

Metadata publication (source and product)

Categorizing content

Deeper in p2

Import Existing Projects into Workspace Select the org.eclipse.pde.build.examples.rcp.cloud.releng.zip archive Choose the org.eclipse.pde.build.examples.rcp.cloud.releng project. Import Plugins and Fragments Import org.eclipse.pde.build as a binary project Running the Example Run buildProduct.xml as Ant Build using the same JRE as the workspace Example: Building with p2

Import Existing Projects into Workspace

Select the org.eclipse.pde.build.examples.rcp.cloud.releng.zip archive

Choose the org.eclipse.pde.build.examples.rcp.cloud.releng project.

Import Plugins and Fragments

Import org.eclipse.pde.build as a binary project

Running the Example

Run buildProduct.xml as Ant Build using the same JRE as the workspace

Slicing repositories The p2.mirror task can easily slice repositories into subset based on given Ius. The example requires p2 bundles, as a demonstration we create a new repository containing the contents of the org.eclipse.equinox.p2.user.ui feature, along with a few other bundles. Specify IUs to mirror into new location Set Slicing Options to include the desired dependencies: includeOptional : whether to include optional dependencies followStrict: only follow strict dependencies (eq: [1.0.0.v2009, 1.0.0.v2009] platformFilter: only mirror Ius matching the given platform filter includeNonGreedy: mirror non-greedy dependencies <p2.mirror source= &quot;${Eclipse.Repo-3.5M6}&quot; destination= &quot;${p2Repo}&quot; > <slicingOptions followStrict= &quot;true&quot; /> <iu id= &quot;org.eclipse.equinox.p2.user.ui.feature.group&quot; /> <iu id= &quot;org.eclipse.ecf&quot; /> <iu id= &quot;org.eclipse.ecf.filetransfer&quot; /> .... <iu id= &quot;org.apache.ant&quot; /> <iu id= &quot;org.eclipse.core.runtime.compatibility.registry&quot; /> </p2.mirror> The <iu> elements also support a “version” attribute, if this attribute is not specified, the highest version found is mirrored. [org.eclipse.pde.build.examples.rcp.cloud.releng/buildProduct.xml createP2Repo]

The p2.mirror task can easily slice repositories into subset based on given Ius.

The example requires p2 bundles, as a demonstration we create a new repository containing the contents of the org.eclipse.equinox.p2.user.ui feature, along with a few other bundles.

Specify IUs to mirror into new location

Set Slicing Options to include the desired dependencies:

includeOptional : whether to include optional dependencies

followStrict: only follow strict dependencies (eq: [1.0.0.v2009, 1.0.0.v2009]

platformFilter: only mirror Ius matching the given platform filter

includeNonGreedy: mirror non-greedy dependencies

The <iu> elements also support a “version” attribute, if this attribute is not specified, the highest version found is mirrored.

Transforming repositories Some bundles must be transformed into folder shape before we can compile against them. p2 provides a task that tranforms bundles into their installed shape. PDE Build has built in support for this using the properties: repoBaseLocation : a folder on disk containing repositories to transform transformedRepoLocation : the destination repository <p2.repo2runnable destination= &quot;${transformedRepoLocation}&quot; > <source dir= &quot;${repoBaseLocation}/&quot; includes= &quot;*&quot; /> </p2.repo2runnable> <source> elements Nested <source> elements are ant filesets that support an extra attribute “ location ” The “ location ” attribute specifies a URL to a repository used for both metadata and artifacts If no “ location ” attribute is specified: folders matched by the fileset are loaded as repositories Files ending in “.zip” are loaded as zipped repositories <iu> elements Nested <iu> elements specify specific IUs to transform If no <iu> elements are specified, the entire repository is transformed [org.eclipse.pde.build/scripts/genericTargets.xml transformRepos]

Some bundles must be transformed into folder shape before we can compile against them.

p2 provides a task that tranforms bundles into their installed shape. PDE Build has built in support for this using the properties:

repoBaseLocation : a folder on disk containing repositories to transform

transformedRepoLocation : the destination repository

<source> elements

Nested <source> elements are ant filesets that support an extra attribute “ location ”

The “ location ” attribute specifies a URL to a repository used for both metadata and artifacts

If no “ location ” attribute is specified:

folders matched by the fileset are loaded as repositories

Files ending in “.zip” are loaded as zipped repositories

<iu> elements

Nested <iu> elements specify specific IUs to transform

If no <iu> elements are specified, the entire repository is transformed

p2 by example Build and repo management Repo management Metadata publication (source and product) Categorizing content Deeper in p2

p2 by example

Build and repo management

Repo management

Metadata publication (source and product)

Categorizing content

Deeper in p2

Publishing metadata Publishing from Source PDE Build extends the publisher and provides an ant tasks to publish to repositories directly from the source for a bundle or feature: Source contains more inputs that can be used to generate metadata (build.properties, p2.inf) Features can have rootfile IUs and artifacts associated with them Allows for some performance gains when over 3.4 style metadata generation. Publishing from Binaries The publisher provides an ant task to publish metadata from binary jars: <p2.publish.featuresAndBundles repository= &quot;file:C:/dev/repo&quot; > <bundles dir= &quot;C:eclipseplugins&quot; includes= &quot;org.eclipse.equinox.launcher_1.0.200.v20090306-1900.jar&quot; /> <features dir= &quot;C:eclipsefeatures&quot; includes= &quot;org.eclipse.rcp_3.5.0.v20090307-9RA-FqhFstOCxSdfkxdojLKc&quot; /> </p2.publish.featuresAndBundles> Both the <bundles> and <features> nested elements are ant filesets specifying folders and jars to publish. PDE Build has an equivalent task “ eclipse.publish.featuresAndBundles ” which does the same but also supports a “ site ” attribute for category generation. [org.eclipse.pde.build.examples.rcp.cloud.releng/buildDirectory/assemble.org.eclipse.pde.build.container.feature.win32.win32.x86.xml]

Publishing from Source

PDE Build extends the publisher and provides an ant tasks to publish to repositories directly from the source for a bundle or feature:

Source contains more inputs that can be used to generate metadata (build.properties, p2.inf)

Features can have rootfile IUs and artifacts associated with them

Allows for some performance gains when over 3.4 style metadata generation.

Publishing from Binaries

The publisher provides an ant task to publish metadata from binary jars:

<p2.publish.featuresAndBundles repository= &quot;file:C:/dev/repo&quot; >

<bundles dir= &quot;C:eclipseplugins&quot; includes= &quot;org.eclipse.equinox.launcher_1.0.200.v20090306-1900.jar&quot; />

<features dir= &quot;C:eclipsefeatures&quot; includes= &quot;org.eclipse.rcp_3.5.0.v20090307-9RA-FqhFstOCxSdfkxdojLKc&quot; />

</p2.publish.featuresAndBundles>

Both the <bundles> and <features> nested elements are ant filesets specifying folders and jars to publish.

PDE Build has an equivalent task “ eclipse.publish.featuresAndBundles ” which does the same but also supports a “ site ” attribute for category generation.

Publishing Products Branding Artifacts PDE Build supports branding artifacts. This will Download input artifact, generally artifacts from org.eclipse.equinox.executable Brand the executable and replace icons Republish the branded artifact using the product id and version [org.eclipse.pde.build.examples.rcp.cloud.relenguildDirectoryassemble.org.eclipse.pde.build.container.feature.p2.xml <eclipse.brand.p2.artifacts>] Publishing the Product The publisher provides an ant task to publish products using a .product file. Allows publishing of products without running a build, provided all required IUs already exist in the repository [org.eclipse.pde.build.examples.rcp.cloud.relenguildDirectoryassemble.org.eclipse.pde.build.container.feature.p2.xml <p2.publisher.product>] Default Configuration IUs PDE Build will generate default configuration IUs for : Setting default start levels Including equinox launchers, setting -startup - -launcher.library [org.eclipse.pde.build.examples.rcp.cloud.relenguildDirectoryfeaturesorg.eclipse.pde.build.container.featureproductp2.inf]

Branding Artifacts

PDE Build supports branding artifacts. This will

Download input artifact, generally artifacts from org.eclipse.equinox.executable

Brand the executable and replace icons

Republish the branded artifact using the product id and version

[org.eclipse.pde.build.examples.rcp.cloud.relenguildDirectoryassemble.org.eclipse.pde.build.container.feature.p2.xml

<eclipse.brand.p2.artifacts>]

Publishing the Product

The publisher provides an ant task to publish products using a .product file.

Allows publishing of products without running a build, provided all required IUs already exist in the repository

[org.eclipse.pde.build.examples.rcp.cloud.relenguildDirectoryassemble.org.eclipse.pde.build.container.feature.p2.xml

<p2.publisher.product>]

Default Configuration IUs

PDE Build will generate default configuration IUs for :

Setting default start levels

Including equinox launchers, setting -startup - -launcher.library

[org.eclipse.pde.build.examples.rcp.cloud.relenguildDirectoryfeaturesorg.eclipse.pde.build.container.featureproductp2.inf]

Running the Director PDE Build now automatically invokes the director for properly configured product builds. (see org.eclipse.pde.build/scripts/genericTargets.xml/runDirector) <java jar= &quot;${equinoxLauncherJar}&quot; fork= &quot;true&quot; failonerror= &quot;true&quot; > <arg line= &quot;-application org.eclipse.equinox.p2.director.app.application&quot; /> <arg line= &quot;-nosplash&quot; /> <arg line= &quot;--launcher.suppressErrors&quot; /> <arg line= &quot;-consoleLog&quot; /> <arg line= &quot;-flavor ${p2.flavor}&quot; /> <arg line= &quot;-installIU ${p2.director.iu}&quot; /> <arg line= &quot;-version ${p2.director.version}&quot; /> <arg line= &quot;-p2.os ${os}&quot; /> <arg line= &quot;-p2.ws ${ws}&quot; /> <arg line= &quot;-p2.arch ${arch}&quot; /> <arg line= &quot;-roaming&quot; /> <arg line= &quot;-profile ${p2.director.profile}&quot; /> <arg line= &quot;${p2.director.extraArgs}&quot; /> <arg line= &quot;-metadataRepository&quot; /> <arg value= &quot;${p2.repo}&quot; /> <arg line= &quot;-artifactRepository&quot; /> <arg value= &quot;${p2.repo}&quot; /> <arg line= &quot;-destination&quot; /> <arg value= &quot;${p2.director.installPath}&quot; /> <arg line= &quot;-bundlepool&quot; /> <arg value= &quot;${p2.director.bundlepool}&quot; /> <jvmarg value= &quot;-Declipse.p2.data.area=${p2.director.dataArea}&quot; /> <jvmarg line= &quot;${p2.director.extraVMArgs}&quot; /> </java> [org.eclipse.pde.build/scripts/genericTargets.xml runDirector]

PDE Build now automatically invokes the director for properly configured product builds.

(see org.eclipse.pde.build/scripts/genericTargets.xml/runDirector)

p2 by example Build and repo management Repo management Metadata publication (source and product) Categorizing content Deeper in p2

p2 by example

Build and repo management

Repo management

Metadata publication (source and product)

Categorizing content

Deeper in p2

Categorizing repository content We define categories using site.xml or category.xml

We define categories using site.xml or category.xml

Creating the category

Categorizing our feature

UpdateSite Publisher ./eclipse -console -consolelog -application org.eclipse.equinox.p2.updatesite.UpdateSitePublisher -metadataRepository file:c:/mail/repository -artifactRepository file:c:/mail/repository -source C:stagingupdateSitecom.example.mail.updatesite -append -publishArtifacts When using the category.xml, use the org.eclipse.equinox.p2.publisher.CategoryPublisher

./eclipse

-console -consolelog

-application org.eclipse.equinox.p2.updatesite.UpdateSitePublisher

-metadataRepository file:c:/mail/repository

-artifactRepository file:c:/mail/repository

-source C:stagingupdateSitecom.example.mail.updatesite

-append

-publishArtifacts

p2 by example Build and repo management Deeper in p2 Additional p2 constructs From plug-ins and features to metadata Plug-ins map Reusing and tweaking the UI Advanced concepts

p2 by example

Build and repo management

Deeper in p2

Additional p2 constructs

From plug-ins and features to metadata

Plug-ins map

Reusing and tweaking the UI

Advanced concepts

Installable Unit Fragments An installable unit fragment is an entity that attaches to an installable unit. Much like OSGi fragments, IU fragments are used to complement an existing installable unit and appear as one with the IU they attached to. They are typically used to deliver configuration information to an installable unit (e.g. start level). IU fragments can be attached to several IU at the same time. See for example the tooling.osgi.bundle.default IU that applies to all bundles. Note that IU fragments are not how OSGi fragments are delivered. OSGi fragments are delivered as regular IU with requirements on their host. Class: IInstallableUnitFragment

An installable unit fragment is an entity that attaches to an installable unit.

Much like OSGi fragments, IU fragments are used to complement an existing installable unit and appear as one with the IU they attached to.

They are typically used to deliver configuration information to an installable unit (e.g. start level).

IU fragments can be attached to several IU at the same time. See for example the tooling.osgi.bundle.default IU that applies to all bundles.

Note that IU fragments are not how OSGi fragments are delivered. OSGi fragments are delivered as regular IU with requirements on their host.

Installable Unit Patches An installable unit patch has the ability to “modify” the requirements of any other installable unit. Deal with three concerns: The IUs to which the patch apply The lifecycle of patch The changes applied Note: In 3.5 the feature patch editor only exposes some of those capabilities. See also http://aniefer.blogspot.com/2009/06/patching-features-with-p2.html

An installable unit patch has the ability to “modify” the requirements of any other installable unit.

Deal with three concerns:

The IUs to which the patch apply

The lifecycle of patch

The changes applied

Installable Units There is only 3 kinds of IU: InstallableUnit, InstallableUnitFragment and InstallableUnitPatch To ease the discussion we use the following terms: Group IU: any IU with the group property set to true. It usually results from the metadata generated for a feature. Product IU: an representing the root of a product (e.g. org.eclipse.sdk.ide). It usually results from the metadata generated for a product. CU: an IU Fragment carrying configuration information (e.g. start level)

There is only 3 kinds of IU:

InstallableUnit, InstallableUnitFragment and InstallableUnitPatch

To ease the discussion we use the following terms:

Group IU: any IU with the group property set to true. It usually results from the metadata generated for a feature.

Product IU: an representing the root of a product (e.g. org.eclipse.sdk.ide). It usually results from the metadata generated for a product.

CU: an IU Fragment carrying configuration information (e.g. start level)

p2 by example Build and repo management Deeper in p2 Additional p2 constructs From plug-ins and features to metadata Plug-ins map Reusing and tweaking the UI Advanced concepts

p2 by example

Build and repo management

Deeper in p2

Additional p2 constructs

From plug-ins and features to metadata

Plug-ins map

Reusing and tweaking the UI

Advanced concepts

Understanding the metadata generated Feature A feature results in two IUs: one capturing the dependencies to other plug-ins and features and one IU representing the feature.jar. Note that ids for the feature being generated are suffixed: org.eclipse.rcp  org.eclipse.rcp.feature.group & org.eclipse.rcp.feature.jar OSGi bundle One IU provides capabilities for : each exported package, indicating that it is a bundle Indicating its bundle name <provided namespace='osgi.bundle' name='org.apache.commons.codec' version='1.3.0'/> <provided namespace='java.package' name='org.apache.commons.codec' version='1.3.0'/> <provided namespace='java.package' name='org.apache.commons.codec.binary' version='1.3.0'/> <provided namespace='java.package' name='org.apache.commons.codec.digest' version='1.3.0'/> <provided namespace='java.package' name='org.apache.commons.codec.language' version='1.3.0'/> <provided namespace='java.package' name='org.apache.commons.codec.net' version='1.3.0'/> <provided namespace='org.eclipse.equinox.p2.eclipse.type' name='bundle' version='1.0.0'/>

Feature

A feature results in two IUs: one capturing the dependencies to other plug-ins and features and one IU representing the feature.jar.

Note that ids for the feature being generated are suffixed:

org.eclipse.rcp  org.eclipse.rcp.feature.group & org.eclipse.rcp.feature.jar

OSGi bundle

One IU provides capabilities for :

each exported package,

indicating that it is a bundle

Indicating its bundle name

Understanding the metadata generated OSGi fragment Same as OSGi bundle plus a capability indicating it is a fragment. The requirement on the host become regular dependencies The exe An IU The config.ini and eclipse.ini Pure metadata. The files are not downloaded they are the result of the installation. Several InstallableUnitFragments (e.g. toolingorg.eclipse.equinox.launcher or toolingorg.eclipse.equinox.simpleconfigurator ). <provided namespace='osgi.fragment' name='org.eclipse.swt' version='3.5.0.v3536b'/> <provided namespace='osgi.bundle' name='org.eclipse.swt.win32.win32.x86' version='3.5.0.v3536b'/> It is important to remember that this is only the metadata generated by the applications provided as part of the publisher, but the metadata is generic and is yours to extend.

OSGi fragment

Same as OSGi bundle plus a capability indicating it is a fragment. The requirement on the host become regular dependencies

The exe

An IU

The config.ini and eclipse.ini

Pure metadata. The files are not downloaded they are the result of the installation.

Several InstallableUnitFragments (e.g. toolingorg.eclipse.equinox.launcher or toolingorg.eclipse.equinox.simpleconfigurator ).

p2 by example Build and repo management Deeper in p2 Additional p2 constructs From plug-ins and features to metadata Plug-ins map Reusing and tweaking the UI Advanced concepts

p2 by example

Build and repo management

Deeper in p2

Additional p2 constructs

From plug-ins and features to metadata

Plug-ins map

Reusing and tweaking the UI

Advanced concepts

Plug-ins map ECF Eclipse touchpoint Native touchpoint Tooling OSGi Update site repository engine Metadata Director Repository UI … …

The minimal set of plug-ins required to provision with p2. They define the core p2 concepts. core Provides some basic infrastructure for most plug-ins. It defines Query, Version and other helpers. metadata Defines the interfaces for the metadata: IInstallableUnit, IUFragment, IUPatch engine Executes a set of operations against a profile. Engine.perform(…) Defines the concept of touchpoint and action: ProvisioningAction Defines profile preference scope Contains the download manager (should not be here ) director Implements the resolution mechanism of p2. Depends on the org.sat4j.* bundles . Core plug-ins ( 1 /2)

The minimal set of plug-ins required to provision with p2. They define the core p2 concepts.

core

Provides some basic infrastructure for most plug-ins. It defines Query, Version and other helpers.

metadata

Defines the interfaces for the metadata: IInstallableUnit, IUFragment, IUPatch

engine

Executes a set of operations against a profile. Engine.perform(…)

Defines the concept of touchpoint and action: ProvisioningAction

Defines profile preference scope

Contains the download manager (should not be here )

director

Implements the resolution mechanism of p2. Depends on the org.sat4j.* bundles .

Core plug-ins (2/2) repository Defines concept of Repository and repository manager. Interfaces with ECF. metadata.repository Defines the metadata repository API and the repository manager. Implements the simple metadata repository (content.jar / content.xml), composite metadata repository. Ant tasks: p2.composite.* to manage composite repos. Application: org.eclipse.equinox.p2.metadata.repository.mirrorApplication. artifact.repository Same than metadata repository for artifacts. Implements processing steps for MD5, pack200 and zipVerifier. Ant tasks: p2.artifact.mirror, p2.composite.artifact.* to manage composite repos [1]. Application: org.eclipse.equinox.p2.artifact.repository.mirrorApplication. garbagecollector Basic garbage collector loop and extension point. Repository and touchpoint agnostic. examplarysetup The plug-in of shame. Pulling all the pieces together. [1] - Ant task - http://wiki.eclipse.org/Equinox/p2_Ant_Tasks

repository

Defines concept of Repository and repository manager. Interfaces with ECF.

metadata.repository

Defines the metadata repository API and the repository manager.

Implements the simple metadata repository (content.jar / content.xml), composite metadata repository.

Ant tasks: p2.composite.* to manage composite repos.

Application: org.eclipse.equinox.p2.metadata.repository.mirrorApplication.

artifact.repository

Same than metadata repository for artifacts.

Implements processing steps for MD5, pack200 and zipVerifier.

Ant tasks: p2.artifact.mirror, p2.composite.artifact.* to manage composite repos [1].

Application: org.eclipse.equinox.p2.artifact.repository.mirrorApplication.

garbagecollector

Basic garbage collector loop and extension point.

Repository and touchpoint agnostic.

examplarysetup

The plug-in of shame. Pulling all the pieces together.

Transport related plug-ins p2 uses ECF because it offers pluggable transport . org.eclipse.equinox.p2.repository Interfacing of p2 with ECF org.eclipse.ecf, org.eclipse.ecf.identity,org.eclipse.ecf.ssl Core ECF bundles org.eclipse.ecf.filetransfer Defines the interface to transfer file with ECF org.eclipse.ecf.provider.filetransfer, org.eclipse.ecf.provider.filetransfer.ssl Provides the implemtation of the service defined in ecf.filetransfer org.eclipse.ecf.provider.filetransfer.httpclient, org.eclipse.ecf.provider.filetransfer.httpclient.ssl Interface ECF with org.apache.commons.httpclient org.apache.commons.httpclient The http client from apache (in 3.5 we are using the 3.0.1 implementation)

p2 uses ECF because it offers pluggable transport .

org.eclipse.equinox.p2.repository

Interfacing of p2 with ECF

org.eclipse.ecf, org.eclipse.ecf.identity,org.eclipse.ecf.ssl

Core ECF bundles

org.eclipse.ecf.filetransfer

Defines the interface to transfer file with ECF

org.eclipse.ecf.provider.filetransfer, org.eclipse.ecf.provider.filetransfer.ssl

Provides the implemtation of the service defined in ecf.filetransfer

org.eclipse.ecf.provider.filetransfer.httpclient, org.eclipse.ecf.provider.filetransfer.httpclient.ssl

Interface ECF with org.apache.commons.httpclient

org.apache.commons.httpclient

The http client from apache (in 3.5 we are using the 3.0.1 implementation)

Eclipse management touchpoint.eclipse Defines the touchpoint and actions necessary to install into eclipse (setStartLevel, installBundle, etc). See [1] fwkadmin Abstract the eclipse touchpoint from the implementation details of a particular OSGi framework. fwkadmin.equinox Implementation of the fwkadmin API for the Equinox framework. It knows how to reason about config.ini and eclipse.ini simpleconfigurator.manipulator Bundles.info writer. simpleconfigurator This bundle is used on startup to tell the OSGi framework what to run. It reads the bundles.info file located in configuration/org.eclipse.equinox.simpleconfgurator/bundles.info [1] – Actions defined by eclipse touchpoint - http://wiki.eclipse.org/Equinox/p2/Engine/Touchpoint_Instructions

touchpoint.eclipse

Defines the touchpoint and actions necessary to install into eclipse (setStartLevel, installBundle, etc). See [1]

fwkadmin

Abstract the eclipse touchpoint from the implementation details of a particular OSGi framework.

fwkadmin.equinox

Implementation of the fwkadmin API for the Equinox framework. It knows how to reason about config.ini and eclipse.ini

simpleconfigurator.manipulator

Bundles.info writer.

simpleconfigurator

This bundle is used on startup to tell the OSGi framework what to run. It reads the bundles.info file located in configuration/org.eclipse.equinox.simpleconfgurator/bundles.info

Native support touchpoint.natives Defines actions such as chmod, link, unzip, etc. [1] [1] – Actions defined by native touchpoint - http://wiki.eclipse.org/Equinox/p2/Engine/Touchpoint_Instructions

touchpoint.natives

Defines actions such as chmod, link, unzip, etc. [1]

UI plug-ins Bundles usable in an eclipse-based application . ui Implementation of the install dialog and wizards. ui.sdk (bogus name alert) Integration of p2 in an application: contribution in the help menu and preference page. ui.sdk.scheduler (bogus name alert) UI affordance and preference page for the update checker. updatechecker Provides the ability to check for an update. This is not a UI bundle.

Bundles usable in an eclipse-based application .

ui

Implementation of the install dialog and wizards.

ui.sdk (bogus name alert)

Integration of p2 in an application: contribution in the help menu and preference page.

ui.sdk.scheduler (bogus name alert)

UI affordance and preference page for the update checker.

updatechecker

Provides the ability to check for an update. This is not a UI bundle.

Repositories implementation p2 allows for alternate repository implementation. Here are few additional ones that are provided. extensionlocation Support to recognize as a repository folders containing the sub folders plugins/ and features directorywatcher Support plug-in for the extension location repository. Monitors the content of the plug-ins folder. updatesite Support for Eclipse legacy update sites. reconciler.dropins Install all the plug-ins and features found into the dropins/ folder. This is not a repository in itself.

p2 allows for alternate repository implementation. Here are few additional ones that are provided.

extensionlocation

Support to recognize as a repository folders containing the sub folders plugins/ and features

directorywatcher

Support plug-in for the extension location repository. Monitors the content of the plug-ins folder.

updatesite

Support for Eclipse legacy update sites.

reconciler.dropins

Install all the plug-ins and features found into the dropins/ folder. This is not a repository in itself.

Misc management bundles director.app Provides a headless way of managing an installation (install / uninstall). App.: org.eclipse.equinox.p2.director.app.application [1] installer Provides an exemplary simple installer using an SWT-based UI. [1] – Director application doc - http://wiki.eclipse.org/Equinox_p2_director_application

director.app

Provides a headless way of managing an installation (install / uninstall).

App.: org.eclipse.equinox.p2.director.app.application [1]

installer

Provides an exemplary simple installer using an SWT-based UI.

Tooling plug-ins Applications and tasks are provided to generate metadata and manage repository publisher A modular and extensible mechanism to generate metadata. Application: org.eclipse.equinox.p2.publisher.*, FeaturesAndBundlesPublisher Ant tasks: p2.publish.product, p2.publish.featureAndBundles, p2.publisher metadata.generator (deprecated in 3.5) Generate metadata from an exported product. repository.tools Provides a set of tools to manage repositories Ant tasks: p2.mirror, p2.repo2Runnable , [1] … jarprocessor Helper tool to sign and pack jars [1] - Ant task - http://wiki.eclipse.org/Equinox/p2_Ant_Tasks

Applications and tasks are provided to generate metadata and manage repository

publisher

A modular and extensible mechanism to generate metadata.

Application: org.eclipse.equinox.p2.publisher.*, FeaturesAndBundlesPublisher

Ant tasks: p2.publish.product, p2.publish.featureAndBundles, p2.publisher

metadata.generator (deprecated in 3.5)

Generate metadata from an exported product.

repository.tools

Provides a set of tools to manage repositories

Ant tasks: p2.mirror, p2.repo2Runnable , [1]

…

jarprocessor

Helper tool to sign and pack jars

p2 by example Build and repo management Deeper in p2 Additional p2 constructs From plug-ins and features to metadata Plug-ins map Reusing and tweaking the UI Advanced concepts

p2 by example

Build and repo management

Deeper in p2

Additional p2 constructs

From plug-ins and features to metadata

Plug-ins map

Reusing and tweaking the UI

Advanced concepts

Tweaking the p2 UI for your audience The UI is split into 3 bundles. p2.ui p2.ui.sdk Integration p2.ui.sdk.scheduler Scheduler

The UI is split into 3 bundles.

p2.ui

p2.ui.sdk

Integration

p2.ui.sdk.scheduler

Scheduler

Add a p2 Preference Page The p2 UI defines a number of preferences Automatic Updates Site selection We need to add a preference page to our RCP application

The p2 UI defines a number of preferences

Automatic Updates

Site selection

We need to add a preference page to our RCP application

Adding Automated Updates and other p2 Preferences Since the p2 bundles are installed, the p2 preferences can be used.

Since the p2 bundles are installed, the p2 preferences can be used.

Remove automatic updates Eliminate: org.eclipse.equinox.p2.ui.sdk.scheduler org.eclipse.equinox.p2.updatechecker RCP Mail no longer supports automatic updates

Eliminate:

org.eclipse.equinox.p2.ui.sdk.scheduler

org.eclipse.equinox.p2.updatechecker

RCP Mail no longer supports automatic updates

Customizing the UI Consider which bundles you need Always include org.eclipse.equinox.p2.ui If you wish to use automatic update checking, include org.eclipse.equinox.p2.updatechecker If you wish to reuse the SDK UI for automatic update include org.eclipse.equinox.p2.ui.sdk.scheduler Configure an instance of org.eclipse.equinox.internal.provisional.p2.ui.policy.Policy

Consider which bundles you need

Always include org.eclipse.equinox.p2.ui

If you wish to use automatic update checking, include org.eclipse.equinox.p2.updatechecker

If you wish to reuse the SDK UI for automatic update include org.eclipse.equinox.p2.ui.sdk.scheduler

Configure an instance of org.eclipse.equinox.internal.provisional.p2.ui.policy.Policy

Example – Control the Update Let’s lock down the application Register a new profile Does not allow users to add sites Group IUs by category

Let’s lock down the application

Register a new profile

Does not allow users to add sites

Group IUs by category

Example – Control the Update

The controlled mode Notice that the entry to choose a site is not available. The preference page to add repo is also removed.

Notice that the entry to choose a site is not available.

The preference page to add repo is also removed.

Granularity of what is visible By default, the p2 UI shows installed roots Configure the UI to show all installed bundles Remove the install history page Reconfigure the installed software page i.e. to remove update

By default, the p2 UI shows installed roots

Configure the UI to show all installed bundles

Remove the install history page

Reconfigure the installed software page

i.e. to remove update

Granularity of what is visible

Updating on Startup Activator startup code must ensure that the p2 infrastructure bundles are started. Otherwise, the required services may not be found when updates are checked.

Activator startup code must ensure that the p2 infrastructure bundles are started. Otherwise, the required services may not be found when updates are checked.

UI code snippets All the p2 UI examples are available at: http://wiki.eclipse.org/Equinox/p2/Adding_Self-Update_to_an_RCP_Application In CVS dev.eclipse.org/cvsroot/rt org.eclipse.equinox/p2/examples

All the p2 UI examples are available at:

http://wiki.eclipse.org/Equinox/p2/Adding_Self-Update_to_an_RCP_Application

In CVS

dev.eclipse.org/cvsroot/rt

org.eclipse.equinox/p2/examples

p2 by example Build and repo management Deeper in p2 Additional p2 constructs From plug-ins and features to metadata Plug-ins map Reusing and tweaking the UI Advanced concepts

p2 by example

Build and repo management

Deeper in p2

Additional p2 constructs

From plug-ins and features to metadata

Plug-ins map

Reusing and tweaking the UI

Advanced concepts

Queryable / Query IQueryable is a general interface for a collection of objects that can be queried Query is what you want to see found Mostly used to find installable units In p2 everything dealing with IUs is queryable MetadataRepository , Profile, result of query… Some default queries are provided (see implementors of Query) InstallableUnitQuery : To find an IU matching an ID and or a version CapabilityQuery: To find an IU providing a capability matching a given requirement IUPropertyQuery: To find an IU with a given property VersionLatestIUVersionQuery : To find the most recent IU

IQueryable is a general interface for a collection of objects that can be queried

Query is what you want to see found

Mostly used to find installable units

In p2 everything dealing with IUs is queryable

MetadataRepository , Profile, result of query…

Some default queries are provided (see implementors of Query)

InstallableUnitQuery : To find an IU matching an ID and or a version

CapabilityQuery: To find an IU providing a capability matching a given requirement

IUPropertyQuery: To find an IU with a given property

VersionLatestIUVersionQuery : To find the most recent IU

Profile A profile is the complete description in terms of IU of what is installed A profile contains Properties defining the “environment” such as os, ws, arch, install location, bundle pool location The list of IUs Properties associated with IUs Class: Org.eclipse.equinox.internal.provisional.p2.engine.IProfile

A profile is the complete description in terms of IU of what is installed

A profile contains

Properties defining the “environment” such as os, ws, arch, install location, bundle pool location

The list of IUs

Properties associated with IUs

Class: Org.eclipse.equinox.internal.provisional.p2.engine.IProfile

Planning a profile change Because of inter IU dependencies, modification against a profile should be planned ProfileChangeRequest Capture the changes you want to make to the profile (e.g. Install, Uninstall). The request is processed by the Planner An update is a removal and an addition Planner The entity responsible for the evaluation of the change request, computing the transitive closure and checking the dependencies If a solution exists it will find it ProvisioningPlan The planner returns a provisioning plan. The planning succeed pass or fail. Upon failure explanations are provided. Upon success the plan returns a set of operands to go from the initial state of the profile to the desired state.

Because of inter IU dependencies,

modification against a profile should be planned

ProfileChangeRequest

Capture the changes you want to make to the profile (e.g. Install, Uninstall).

The request is processed by the Planner

An update is a removal and an addition

Planner

The entity responsible for the evaluation of the change request, computing the transitive closure and checking the dependencies

If a solution exists it will find it

ProvisioningPlan

The planner returns a provisioning plan. The planning succeed pass or fail. Upon failure explanations are provided. Upon success the plan returns a set of operands to go from the initial state of the profile to the desired state.

Engine The mechanism by which the profile is actually changed Runs over a set of operands (usually resulting from a planning operation) and executes a given set of phases on them. No profile consistency validation is done Engine.perform(Operand[] ops, PhaseSet phases, IProgressMonitor pm) For each phase, the engine interprets from the touchpoint data of the IU, the action specific to the phase. The engine looks up the action to execute. Currently 8 phases are defined, and the typical set of phases (and their order) is defined in DefaultPhaseSet . The design allows for new phases could be added, however this would engage serious coding. The engine ensures consistency of the modification by performing a “transaction”. The engine emit events on the IProvisoningEventBus to describe what is happening. Events on the bus are post events and can not be vetoed.

The mechanism by which the profile is actually changed

Runs over a set of operands (usually resulting from a planning operation) and executes a given set of phases on them. No profile consistency validation is done

Engine.perform(Operand[] ops, PhaseSet phases, IProgressMonitor pm)

For each phase, the engine interprets from the touchpoint data of the IU, the action specific to the phase. The engine looks up the action to execute.

Currently 8 phases are defined, and the typical set of phases (and their order) is defined in DefaultPhaseSet . The design allows for new phases could be added, however this would engage serious coding.

The engine ensures consistency of the modification by performing a “transaction”.

The engine emit events on the IProvisoningEventBus to describe what is happening. Events on the bus are post events and can not be vetoed.

Engine flowchart

Touchpoint / actions The decoupling between p2 and the actual system being modified. It defines how to modify a particular “runtime”. An action is a piece of code in charge of changing the system (e.g installing a bundle, setting a start level, etc.). An action can be context free or context bound. See ProvisioningAction Example of context free: chmod , unzip Example of context bound: installBundle , setStartLevel ,… A touchpoint provides the context in which an action is executed For example the eclipse touchpoint provides its actions values such as the eclipse install folder, the bundle pool and is also used to cache some common data structure (e.g. the state of the fwk being modified) The extension point for touchpoint and actions is defined in the engine.

The decoupling between p2 and the actual system being modified.

It defines how to modify a particular “runtime”.

An action is a piece of code in charge of changing the system (e.g installing a bundle, setting a start level, etc.). An action can be context free or context bound. See ProvisioningAction

Example of context free: chmod , unzip

Example of context bound: installBundle , setStartLevel ,…

A touchpoint provides the context in which an action is executed

For example the eclipse touchpoint provides its actions values such as the eclipse install folder, the bundle pool and is also used to cache some common data structure (e.g. the state of the fwk being modified)

The extension point for touchpoint and actions is defined in the engine.

Engine and actions put together

Artifact processor Artifacts can be stored in various format (e.g. pack200, jar, diff) A processor is responsible for transforming an artifact from its “stored” form to its canonical form. Processors can also be used to “look at” the bytes as they are coming through MD5, zip verifier, Mandatory steps are mentioned in the artifact descriptor in the artifact repository <example> Implementation detail: The download manager looks at the various shapes under which an artifact is made available and always prefer the non-canonical one. Ex t ension point: org.eclipse.equinox.p2.artifactRepository.ProcessingStep

Artifacts can be stored in various format (e.g. pack200, jar, diff)

A processor is responsible for transforming an artifact from its “stored” form to its canonical form.

Processors can also be used to “look at” the bytes as they are coming through

MD5, zip verifier,

Mandatory steps are mentioned in the artifact descriptor in the artifact repository

<example>

Implementation detail:

The download manager looks at the various shapes under which an artifact is made available and always prefer the non-canonical one.

Ex t ension point: org.eclipse.equinox.p2.artifactRepository.ProcessingStep

Canonical JBDiff Artifact Repository Pack200 Pack200 Processor Artifact processor, illustrated

References p2 landing page http://wiki.eclipse.org/Equinox_p2 All p2 articles http://wiki.eclipse.org/Category:Equinox_p2 Getting the code http://wiki.eclipse.org/Equinox_p2_Getting_Started_for_Developers Contacting us Equinox newsgroup Mailing list: p2-dev@eclipse.org

p2 landing page http://wiki.eclipse.org/Equinox_p2

All p2 articles http://wiki.eclipse.org/Category:Equinox_p2

Getting the code http://wiki.eclipse.org/Equinox_p2_Getting_Started_for_Developers

Contacting us

Equinox newsgroup

Mailing list: p2-dev@eclipse.org

Thank you

F.A.Q.

Bundle Pooling Every profile has a bundle pool location Shared pool -> multiple profiles share bundles Save download time/bandwidth Save disk space Possible memory savings depending on JRE Can be setup with installer or admin UI

Every profile has a bundle pool location

Shared pool -> multiple profiles share bundles

Save download time/bandwidth

Save disk space

Possible memory savings depending on JRE

Can be setup with installer or admin UI

Installing just a plug-in It is possible, just grab the IU and install it. The default p2 UI is not allowing for this to not overwhelm users To have p2 metadata for it, you still have to have a feature (PDE restriction)

It is possible, just grab the IU and install it.

The default p2 UI is not allowing for this to not overwhelm users

To have p2 metadata for it, you still have to have a feature (PDE restriction)

Boot sequence Without dropins Simpleconfigurator reads bundles.info and apply it (note that if bundles.info has not changed, nothing is done). p2 bundles are not loaded until p2 functionality is invoked (e.g open the UI) With dropins Simpleconfigurator reads bundles.info and apply it (note that if bundles.info has not changed, nothing is done). Reconciler bundles is started Reconciler finds the bundles in the dropins folder and take them through a complete installation phase. A new profile file and a new bundles.info are written Reconciler re-invoke simpleconfigurator to read bundles.info

Without dropins

Simpleconfigurator reads bundles.info and apply it (note that if bundles.info has not changed, nothing is done).

p2 bundles are not loaded until p2 functionality is invoked (e.g open the UI)

With dropins

Simpleconfigurator reads bundles.info and apply it (note that if bundles.info has not changed, nothing is done).

Reconciler bundles is started

Reconciler finds the bundles in the dropins folder and take them through a complete installation phase. A new profile file and a new bundles.info are written

Reconciler re-invoke simpleconfigurator to read bundles.info

Missing requirements The cause of an error indicating a missing requirement usually are: Missing capabilities: no IU in the repository provides the capability necessary to the satisfaction of the requirement. Bogus filter on the IU that could satisfy the requirement Missing IU: the IU satisfying the requirement is not available in the repositories being consulted

The cause of an error indicating a missing requirement usually are:

Missing capabilities: no IU in the repository provides the capability necessary to the satisfaction of the requirement.

Bogus filter on the IU that could satisfy the requirement

Missing IU: the IU satisfying the requirement is not available in the repositories being consulted