Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

Platform Plug-in Developer Guide Programmer's Guide Provisioning platform, p2

Installing software using the p2 director application

In addition to the "Software Updates" dialog, you can also perform provisioning operations from a command line or script. This is achieved using a tool called the director application. The director application is a command line tool for installing additional software or uninstalling software from an Eclipse-based product. This application is capable of provisioning a complete installation from scratch or simply extending your application. Depending on your needs, this application can be executed both inside and outside of the target product 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.
Builder: an eclipse based application containing the director application bundle and its depents.

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


  <targetProductFolder>/eclipsec.exe 
   -application org.eclipse.equinox.p2.director 
   -repository https://download.eclipse.org/releases/galileo/
   -installIU org.eclipse.cdt.feature.group/<version>

Provisioning without running the target application

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

This 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 linux machine, one can add plug-ins to a windows-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 for the "inside" mode need to be set. These mostly consist in providing 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" containing the builder, you want to install CDT into an existing SDK located into "d:\eclipse", you would use the following command line.


   d:\builder\eclipsec.exe
   -application org.eclipse.equinox.p2.director
   -repository https://download.eclipse.org/releases/galileo/
   -installIU org.eclipse.cdt.feature.group
   -destination d:/eclipse/
   -profile SDKProfile

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

Installing a complete product

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

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


   d:\builder\eclipsec.exe
   -application org.eclipse.equinox.p2.director
   -repository https://download.eclipse.org/eclipse/updates/3.5
   -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

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

Arguments Description

-application org.eclipse.equinox.p2.director: the application ID.
-metadataRepository: a comma separated list of metadata repository URLs where the software to be installed can be found.
-artifactRepository: a comma separated list of artifact repository URLs where the software artifacts can be found.
-repository: a comma separated list of repository URL where each entry denotes colocated meta-data and artifact repositories.
-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> ].
-destination: the path of a folder in which the targeted product is located.
-list: lists all IU's found in the given repositories.
-profile: the profile id containing the description of the targeted product. This ID is is defined by the 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.
-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.
-shared: use a shared location for the install. The path defaults to ${user.home}/.p2.
-verifyOnly: only verify that the actions can be performed. Don't actually install or remove anything.

While doing these operations, you can disable the automatic mirror selection mechanism by setting the VM argument eclipse.p2.mirrors to false.