Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Equinox/p2/Getting Started for Releng"
(→Why do I need to make changes to adopt p2?) |
|||
| (15 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
| − | The Eclipse Ganymede (3.4) release introduces [[ | + | The Eclipse Ganymede (3.4) release introduces [[Equinox p2]], a new platform for installing, managing, and updating Eclipse-based applications and extensions. p2 offers significantly improved functionality over the platform Update Manager used in previous releases. Leveraging this new functionality requires some changes for people building and assembling Eclipse-based applications and add-ons. This article helps buildmeisters and release engineers to get started with adopting p2. See also [[Equinox p2 Getting Started]] for an introduction to p2 from an end-user perspective. |
| − | = Why | + | = Why should I make changes to adopt p2? = |
p2 offers significant advances over the Update Manager found in previous versions of the platform. Some advances include: | p2 offers significant advances over the Update Manager found in previous versions of the platform. Some advances include: | ||
| Line 10: | Line 10: | ||
* Dynamic discovery and high-fidelity resolution of software dependencies. | * Dynamic discovery and high-fidelity resolution of software dependencies. | ||
| − | These advances require additional metadata about the software being installed above the information in the feature.xml and site.xml files used by Update Manager. Feature.xml files provide an incomplete picture of software dependencies - they are essentially a coarse-grained subset of the dependencies expressed in the plug-in manifest | + | These advances require additional metadata about the software being installed above the information in the feature.xml and site.xml files used by Update Manager. Feature.xml files provide an incomplete picture of software dependencies - they are essentially a coarse-grained subset of the dependencies expressed in the plug-in manifest files (MANIFEST.MF). p2 metadata includes a complete description of these dependencies, allowing it to be 100% accurate about resolving dependencies at install-time. With p2, you can pick a single plug-in to install, and p2 will be able to compute the complete set of plug-ins and other artifacts required to satisfy the runtime requirements of that plug-in. To accomplish this, p2 needs to either obtain or create this high-fidelity dependency information at install-time. |
Update Manager only supported adding additional content, or upgrading existing content, in an Eclipse-based application. It did not allow you to provision an entire application from scratch, including launchers and other files that were not plug-ins or features. p2 can install and update entire applications, including all these non plug-in/feature bits. To accomplish this, p2 needs to obtain or create the necessary metadata to reason about these artifacts and their dependencies. | Update Manager only supported adding additional content, or upgrading existing content, in an Eclipse-based application. It did not allow you to provision an entire application from scratch, including launchers and other files that were not plug-ins or features. p2 can install and update entire applications, including all these non plug-in/feature bits. To accomplish this, p2 needs to obtain or create the necessary metadata to reason about these artifacts and their dependencies. | ||
| − | The reason build and release engineering teams | + | The reason build and release engineering teams should take steps to adopt p2 is to produce this p2 metadata that allows p2 to support this new level of functionality. |
= What do I need to do to adopt p2? = | = What do I need to do to adopt p2? = | ||
| Line 22: | Line 22: | ||
== Zips of plug-ins and features == | == Zips of plug-ins and features == | ||
| − | If your project produces zips of plug-ins and features for consumption by others, no action is required. p2 provides a number of ways for an end-user to install such zips: | + | If your project produces zips of plug-ins and features for consumption by others, no action is strictly required. p2 provides a number of ways for an end-user to install such zips: |
* Drag into the "Software Updates" dialog in the UI | * Drag into the "Software Updates" dialog in the UI | ||
| Line 28: | Line 28: | ||
* Unzip directly on eclipse root directory (generally not recommended as it makes it difficult to distinguish added content from the base application). | * Unzip directly on eclipse root directory (generally not recommended as it makes it difficult to distinguish added content from the base application). | ||
| − | However, when p2 encounters raw plug-ins and features, it needs to do some processing on the content to compute p2 metadata. This results in a slower experience for the end user when the content is first installed. You can optimize this by creating a p2 repository that contains your plugins and features. A p2 repository is created automatically if you export plug-ins and features from your IDE using the PDE plug-in export wizard. This adds a ''content.xml'' and ''artifacts.xml''. p2 also provides a ''p2.generator'' Ant task or stand-alone application that can be invoked programmatically or from a build script to produce a p2 repository. See [[Equinox p2 Metadata Generator]] for more information about | + | However, when p2 encounters raw plug-ins and features, it needs to do some processing on the content to compute p2 metadata. This results in a slower experience for the end user when the content is first installed. You can optimize this by creating a p2 repository that contains your plugins and features. A p2 repository is created automatically if you export plug-ins and features from your IDE using the PDE plug-in export wizard. This adds a ''content.xml'' and ''artifacts.xml''. p2 also provides a ''p2.generator'' Ant task or stand-alone application that can be invoked programmatically or from a build script to produce a p2 repository. See [[Equinox p2 Metadata Generator]] for more information about the p2 generator application. |
== Update sites == | == Update sites == | ||
| − | If you currently produce an Eclipse Update Site (site.xml), there is also no action required. p2 can install plug-ins and features directly from existing update sites produced for earlier releases of the Eclipse Platform. However, p2 needs to produce its metadata on the fly when a simple update site is encountered. | + | If you currently produce an Eclipse Update Site (site.xml), there is also no action required. p2 can install plug-ins and features directly from existing update sites produced for earlier releases of the Eclipse Platform. However, p2 needs to produce its metadata on the fly when a simple update site is encountered. This results in a slower experience for the end user when installing content from update sites. To eliminate this slowness, it is recommended that you ''p2-enable'' your update site by running the p2 update site publisher on it. This will add p2 metadata in the form of a content.xml and artifacts.xml file to your update site. See [[Equinox/p2/Publisher]] for more information about the p2 update site publisher application. |
| + | |||
| + | ===Artifacts.xml mapping rule change=== | ||
| + | By default, a SimpleArtifactRepository (artifacts.xml / artifacts.jar) looks for plug-ins and features in a subfolder of the repository. This is driven by mapping rules found in the artifacts.xml. this is a filter where the first entry to match wins (rules have to be specified from the most specific to the least). Here are for example the default rules for the Galileo repository: | ||
| + | <mappings size="5"> | ||
| + | <rule filter='(& (classifier=osgi.bundle) (format=packed))' output='${repoUrl}/plugins/${id}_${version}.jar.pack.gz'/> | ||
| + | <rule filter='(& (classifier=osgi.bundle))' output='${repoUrl}/plugins/${id}_${version}.jar'/> | ||
| + | <rule filter='(& (classifier=binary))' output='${repoUrl}/binary/${id}_${version}'/> | ||
| + | <rule filter='(& (classifier=org.eclipse.update.feature) (format=packed))' output='${repoUrl}/features/${id}_${version}.jar.pack.gz'/> | ||
| + | <rule filter='(& (classifier=org.eclipse.update.feature))' output='${repoUrl}/features/${id}_${version}.jar'/> | ||
| + | </mappings> | ||
| + | It is possible to change those rules to have a filter matching for a particular artifact and change the output to point to a specific location. Rules are specified in the ''mappings'' section of the artifacts.xml file. For example to make p2 to download the <code>org.sat4j.pb</code> plug-in through the eclipse.org download script (which provides download tracking) add the following line: | ||
| + | <rule filter='(& (id=org.sat4j.pb) (classifier=osgi.bundle))' | ||
| + | output='http://www.eclipse.org/downloads/download.php?file=/eclipse/updates/3.5milestones/S-3.5RC3-200905282000/plugins/${id}_${version}.jar'/> | ||
| + | To make p2 download the <code>org.eclipse.platform</code> feature using the eclipse.org download script, add the following line: | ||
| + | <rule filter='(& (id=org.eclipse.platform) (classifier=org.eclipse.update.feature)' | ||
| + | output='http://www.eclipse.org/downloads/download.php?file=/eclipse/updates/3.5milestones/S-3.5RC3-200905282000/features/${id}_${version}.jar'/> | ||
| + | Order is important. | ||
| + | |||
| + | == Complete applications == | ||
| + | |||
| + | If you currently produce your own Eclipse-based application, the action required for adopting p2 depends on exactly how you are building the application. | ||
| + | |||
| + | === Applications created by dropping bundles on top of an existing application === | ||
| + | |||
| + | If you currently create your own application by dropping extra plug-ins or features into an existing application (such as the Eclipse Platform application), then no action is required. When the application first starts, your bundles will be detected and corresponding p2 metadata will be generated. | ||
| + | |||
| + | However, there are some advantages to p2-enabling your application. This involves creating p2 metadata to represent the bundles in your application, and also to represent your application as a whole within p2 metadata. This would enable p2 to install or update your entire application, including non-bundle configuration files, as a single unit. | ||
| + | |||
| + | To p2-enable your application, run the [[Equinox p2 Metadata Generator]] on it. This will produce a p2 repository containing both p2 metadata for your application, and an artifact repository containing the bundles and other artifacts in your application. From this repository a p2 install operation can be executed to install your application (for example with the [[Equinox p2 Installer]], or the [[Equinox p2 director application]]). | ||
| + | |||
| + | === Applications created by using PDE product build === | ||
| + | |||
| + | Add the following properties to your '''build.properties''' file: | ||
| + | |||
| + | generate.p2.metadata=true | ||
| + | p2.metadata.repo = file:${buildDirectory}/repo | ||
| + | p2.artifact.repo = file:${buildDirectory}/repo | ||
| + | p2.metadata.repo.name = Meta Repo Name | ||
| + | p2.artifact.repo.name = Artifact Repo Name | ||
| + | p2.flavor = tooling | ||
| + | p2.publish.artifacts=true | ||
| + | |||
| + | This will generate a metadata/artifact repository that can be used for installing the application. You can test this by creating your own ''installer.properties'' file pointing to the newly created repository and use the [[Equinox p2 Installer]]. For instance: | ||
| + | |||
| + | eclipse.p2.rootId=foo.bar.product | ||
| + | eclipse.p2.metadata=file:///var/build/product/repo | ||
| + | eclipse.p2.artifacts=file:///var/build/product/repo | ||
| + | eclipse.p2.launcherName=product | ||
| + | eclipse.p2.autoStart=true | ||
| + | |||
| + | Then launch the installer using: | ||
| + | p2installer -vmargs -Dorg.eclipse.equinox.p2.installDescription=file:installer.properties | ||
| + | |||
| + | |||
[[Category:Equinox p2|Releng]] | [[Category:Equinox p2|Releng]] | ||
Latest revision as of 15:29, 3 January 2011
The Eclipse Ganymede (3.4) release introduces Equinox p2, a new platform for installing, managing, and updating Eclipse-based applications and extensions. p2 offers significantly improved functionality over the platform Update Manager used in previous releases. Leveraging this new functionality requires some changes for people building and assembling Eclipse-based applications and add-ons. This article helps buildmeisters and release engineers to get started with adopting p2. See also Equinox p2 Getting Started for an introduction to p2 from an end-user perspective.
Why should I make changes to adopt p2?
p2 offers significant advances over the Update Manager found in previous versions of the platform. Some advances include:
- The ability to install complete Eclipse-based applications from scratch, above just augmenting and updating already installed applications.
- The ability to install and manage an application from either inside the application or from another process.
- The ability to install and manage artifacts other than plug-ins and features, such as launchers, root files such as licenses, configuration files, Java VMs, etc.
- Dynamic discovery and high-fidelity resolution of software dependencies.
These advances require additional metadata about the software being installed above the information in the feature.xml and site.xml files used by Update Manager. Feature.xml files provide an incomplete picture of software dependencies - they are essentially a coarse-grained subset of the dependencies expressed in the plug-in manifest files (MANIFEST.MF). p2 metadata includes a complete description of these dependencies, allowing it to be 100% accurate about resolving dependencies at install-time. With p2, you can pick a single plug-in to install, and p2 will be able to compute the complete set of plug-ins and other artifacts required to satisfy the runtime requirements of that plug-in. To accomplish this, p2 needs to either obtain or create this high-fidelity dependency information at install-time.
Update Manager only supported adding additional content, or upgrading existing content, in an Eclipse-based application. It did not allow you to provision an entire application from scratch, including launchers and other files that were not plug-ins or features. p2 can install and update entire applications, including all these non plug-in/feature bits. To accomplish this, p2 needs to obtain or create the necessary metadata to reason about these artifacts and their dependencies.
The reason build and release engineering teams should take steps to adopt p2 is to produce this p2 metadata that allows p2 to support this new level of functionality.
What do I need to do to adopt p2?
The following sections describe steps to adopting p2 depending on what kind of outputs your project produces.
Zips of plug-ins and features
If your project produces zips of plug-ins and features for consumption by others, no action is strictly required. p2 provides a number of ways for an end-user to install such zips:
- Drag into the "Software Updates" dialog in the UI
- Unzip into the eclipse/dropins folder
- Unzip directly on eclipse root directory (generally not recommended as it makes it difficult to distinguish added content from the base application).
However, when p2 encounters raw plug-ins and features, it needs to do some processing on the content to compute p2 metadata. This results in a slower experience for the end user when the content is first installed. You can optimize this by creating a p2 repository that contains your plugins and features. A p2 repository is created automatically if you export plug-ins and features from your IDE using the PDE plug-in export wizard. This adds a content.xml and artifacts.xml. p2 also provides a p2.generator Ant task or stand-alone application that can be invoked programmatically or from a build script to produce a p2 repository. See Equinox p2 Metadata Generator for more information about the p2 generator application.
Update sites
If you currently produce an Eclipse Update Site (site.xml), there is also no action required. p2 can install plug-ins and features directly from existing update sites produced for earlier releases of the Eclipse Platform. However, p2 needs to produce its metadata on the fly when a simple update site is encountered. This results in a slower experience for the end user when installing content from update sites. To eliminate this slowness, it is recommended that you p2-enable your update site by running the p2 update site publisher on it. This will add p2 metadata in the form of a content.xml and artifacts.xml file to your update site. See Equinox/p2/Publisher for more information about the p2 update site publisher application.
Artifacts.xml mapping rule change
By default, a SimpleArtifactRepository (artifacts.xml / artifacts.jar) looks for plug-ins and features in a subfolder of the repository. This is driven by mapping rules found in the artifacts.xml. this is a filter where the first entry to match wins (rules have to be specified from the most specific to the least). Here are for example the default rules for the Galileo repository:
<mappings size="5">
<rule filter='(& (classifier=osgi.bundle) (format=packed))' output='${repoUrl}/plugins/${id}_${version}.jar.pack.gz'/>
<rule filter='(& (classifier=osgi.bundle))' output='${repoUrl}/plugins/${id}_${version}.jar'/>
<rule filter='(& (classifier=binary))' output='${repoUrl}/binary/${id}_${version}'/>
<rule filter='(& (classifier=org.eclipse.update.feature) (format=packed))' output='${repoUrl}/features/${id}_${version}.jar.pack.gz'/>
<rule filter='(& (classifier=org.eclipse.update.feature))' output='${repoUrl}/features/${id}_${version}.jar'/>
</mappings>
It is possible to change those rules to have a filter matching for a particular artifact and change the output to point to a specific location. Rules are specified in the mappings section of the artifacts.xml file. For example to make p2 to download the org.sat4j.pb plug-in through the eclipse.org download script (which provides download tracking) add the following line:
<rule filter='(& (id=org.sat4j.pb) (classifier=osgi.bundle))' output='http://www.eclipse.org/downloads/download.php?file=/eclipse/updates/3.5milestones/S-3.5RC3-200905282000/plugins/${id}_${version}.jar'/>
To make p2 download the org.eclipse.platform feature using the eclipse.org download script, add the following line:
<rule filter='(& (id=org.eclipse.platform) (classifier=org.eclipse.update.feature)' output='http://www.eclipse.org/downloads/download.php?file=/eclipse/updates/3.5milestones/S-3.5RC3-200905282000/features/${id}_${version}.jar'/>
Order is important.
Complete applications
If you currently produce your own Eclipse-based application, the action required for adopting p2 depends on exactly how you are building the application.
Applications created by dropping bundles on top of an existing application
If you currently create your own application by dropping extra plug-ins or features into an existing application (such as the Eclipse Platform application), then no action is required. When the application first starts, your bundles will be detected and corresponding p2 metadata will be generated.
However, there are some advantages to p2-enabling your application. This involves creating p2 metadata to represent the bundles in your application, and also to represent your application as a whole within p2 metadata. This would enable p2 to install or update your entire application, including non-bundle configuration files, as a single unit.
To p2-enable your application, run the Equinox p2 Metadata Generator on it. This will produce a p2 repository containing both p2 metadata for your application, and an artifact repository containing the bundles and other artifacts in your application. From this repository a p2 install operation can be executed to install your application (for example with the Equinox p2 Installer, or the Equinox p2 director application).
Applications created by using PDE product build
Add the following properties to your build.properties file:
generate.p2.metadata=true
p2.metadata.repo = file:${buildDirectory}/repo
p2.artifact.repo = file:${buildDirectory}/repo
p2.metadata.repo.name = Meta Repo Name
p2.artifact.repo.name = Artifact Repo Name
p2.flavor = tooling
p2.publish.artifacts=true
This will generate a metadata/artifact repository that can be used for installing the application. You can test this by creating your own installer.properties file pointing to the newly created repository and use the Equinox p2 Installer. For instance:
eclipse.p2.rootId=foo.bar.product eclipse.p2.metadata=file:///var/build/product/repo eclipse.p2.artifacts=file:///var/build/product/repo eclipse.p2.launcherName=product eclipse.p2.autoStart=true
Then launch the installer using:
p2installer -vmargs -Dorg.eclipse.equinox.p2.installDescription=file:installer.properties