Jump to: navigation, search

Equinox/p2/Director application

The director application is a headless way of performing some of the p2 operations such as installing or uninstalling installable units. Given the appropriate metadata, this application is capable of provisioning a complete installation from scratch or simply extending your application.

Depending on the needs, this application can be executed inside or outside of the application being provisioned


Terminology

Director application 
the application performing p2 operations such as install or uninstall. This application is provided by the org.eclipse.equinox.p2.director.app bundle.
Provisioning operation 
an operation installing, uninstalling features.
Target product 
the installation targeted by the provisioning operation.

Running inside the target application

In this mode, the provisioning operation happens from within the targeted product that you are provisioning. It is equivalent to starting up the targeted product and using the p2 UI to perform the equivalent operation.

This means that the target application has to be in a runnable state and that it has to contain the director application bundle. Also since the target product will have run, cache files will have been created in the configuration folder (e.g. configuration/org.eclipse.osgi).

The following example shows the command line used to install CDT into the SDK.

   java -jar <targetProductFolder>/plugins/org.eclipse.equinox.launcher_*.jar
   -application org.eclipse.equinox.p2.director 
   -metadataRepository file:d:/tmp/cdt/site.xml 
   -artifactRepository file:d:/tmp/cdt/site.xml
   -installIU org.eclipse.cdt.feature.group

Note that this mode is equivalent to the former update manager command line application (http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/update_standalone.html).

Provisioning without running the target application

In this case the provisioning operation is happening "outside" of the targeted product. The "targeted product" is *not* started. This allows to both modify an existing installation and create a complete installation from scratch given proper metadata.

It also has the advantage that since the targeted product does not need to be started, the provisioning operation can be performed on any platform for any other platform (e.g. on my windows machine, I can create add plug-ins to a linux-based target application).

Installing / uninstalling IUs into a target product

To install or uninstall something into an existing target product a few extra arguments than in the "inside" mode need to be set. It mostly consist in letting the provisioning operation the ID of the profile it needs to operate on, and where it is located on disk.

For example, if from a directory called "d:\builder", you want to install CDT into an existing SDK located into "d:\eclipse", you would use the following command line. It is important to note the presence of the VM args and set it properly.

   java -jar <targetProductFolder>/plugins/org.eclipse.equinox.launcher_*.jar
   -application org.eclipse.equinox.p2.director
   -metadataRepository file:d:/tmp/cdt/site.xml
   -artifactRepository file:d:/tmp/cdt/site.xml
   -installIU org.eclipse.cdt.feature.group
   -destination d:/eclipse/
   -profile SDKProfile
   
   -vmArgs
   -Declipse.p2.data.area=d:/eclipse/p2

Note that there is no need to describe the os/ws/arch of the platform being targeted because all this information is already being available in the profile.

Installing a complete product

The creation of a complete product using the director application only needs a few extra arguments to the previous example. Most of these consist in values used to initialize the profile in which the application will be provisioned.

The following example demonstrate how to create a linux/gtk installation of the Eclipse SDK into a folder called "d:\eclipse" using a director application located in "d:\builder".

   java -jar <targetProductFolder>/plugins/org.eclipse.equinox.launcher_*.jar
   -application org.eclipse.equinox.p2.director
   -metadataRepository http://update.eclipse.org/testUpdates
   -artifactRepository http://update.eclipse.org/testUpdates
   -installIU org.eclipse.sdk.ide
   -destination d:/eclipse/
   -profile SDKProfile
   -profileProperties org.eclipse.update.install.features=true
   -bundlepool d:/eclipse/
   -p2.os linux
   -p2.ws gtk
   -p2.arch x86
   -roaming
   
   -vmargs
   -Declipse.p2.data.area=d:/eclipse/p2

The -p2.* arguments describe the os/ws/arch that the provisioned product is targeting.

Here again notice the presence of the -vmargs pointing at the eclipse data area for the installation being created.

Arguments Description

-application org.eclipse.equinox.p2.director 
the application ID. Before Galileo, the application ID is org.eclipse.equinox.p2.director.app.application
-metadataRepository 
a comma separated list of metadata repositories where the installable units to be installed can be found. Must be in URL format, so local repositories would use file:///path/to/local/repo
-artifactRepository 
a comma separated list of artifact repositories where the artifacts can be found. Must be in URL format, so local repositories would use file:///path/to/local/repo
-installIU 
a comma separated list of IUs to install. Each entry in the list is in the form <id> [ '/' <version> ]. If you are looking to install a feature, the identifier of the feature has to be suffixed with ".feature.group".
-uninstallIU 
a comma separated list of IUs to uninstall. Each entry in the list is in the form <id> [ '/' <version> ].
-revert 
Revert the installation to a previous state [ the number representing the previous state of the profile as found in p2/org.eclipse.equinox.p2.engine/<profileId>/ ].
-destination 
the folder in which the targeted product is located.
-list 
lists all IU's found in the given repositories in a property like format. IUs can optionally be listed. Each entry in the list is in the form <id> [ '/' <version> ].
-profile 
the profile id containing the description of the targeted product. This ID is usually found eclipse.p2.profile property contained in the config.ini of the targeted product. For the Eclipse SDK the ID is "SDKProfile"
-profileProperties 
a comma separated list of <key>=<value> pair. The property org.eclipse.update.install.features=true will cause the update manager features to be installed.
eclipse.p2.data.area 
this property points at location of the profile registry containing the description of the profile set in "-profile". It is recommended to set it to be <destination>/p2. This property *must* be set as a VM argument.
-bundlepool 
the location of where the plug-ins and features will be stored. This value is only taken into account when a new profile is created. For an application where all the bundles are located into the plugins/ folder of the destination, set it to <destination>.
-p2.os 
the OS to use when the profile is created. This will be used to filter which OS specific installable units need to be installed.
-p2.ws 
the windowing system to use when the profile is created. This will be used to filter which WS specific installable units need to be installed.
-p2.arch 
the architecture to use when the profile is created. This will be used to filter which architecture specific installable units need to be installed.
-roaming 
indicates that the product resulting from the installation can be moved. This property only makes sense when the destination, bundle pool are in the same location and eclipse.p2.data.area is set to destination/p2. This value is only taken into account when the profile is created.

Additional VM Arguments

These can be set using -vmargs:

-Declipse.p2.mirrors=false 
disable checking mirrors when resolving IUs

Scripted Examples

See Also