P2 Install Example

Set up P2 Eclipse Environment

• Get p2 from CVS

To get started, you will need the source code for p2. This is best done by following the steps outlined at Equinox p2 Getting Started for Developers

• Create RCP Application

We want to create an RCP Application through the 3.4 Eclipse SDK so that we have something to publish thereby creating a local artifact and metadata repository that the p2 tooling can use. To do this,

From Eclipse, File->New->Other
Select Plug-in Project
Specify a project name (com.eclipse.cosmos.testp2app)
Click Next
Select Yes for Create a Rich Client Application
Click Next
Choose RCP Application with a View

Once you click Finish, this will create a MAINFEST.MF file and open the file in the eclipse viewer window.

• Test RCP application from MANIFEST.MF file.

To test the application, from the Overview tab click the Launch an Eclipe application button. This should launch the application and you will get a window displayed of your test application.

Set up Product

• Create Product Configuration

The product configuration is used to specify the necessary bundles that the application relies on so that it can perform the necessary dependency checks and have the components available when it runs. To do this,

From Eclispe, highlight the plugin project (com.eclipse.cosmos.testp2app) that we created.
Select from the menu bar File-New->Product Configuration
Specify a filename. (testp2app)
Click Ok.

This will display the testp2app.product edit page.

From the testp2app.product edit page, we will now specify the product definition.

Enter a name (testp2)
For the id, select New button. From dialog, click Ok.
Enter a version (1.0.0)

• Specify Configuration

Now we will add the bundles necessary.

From Configuration tab, click add.
In the Add dialog, right click and select all.
Click Ok.

This will add the bundles necessary to run the app. Make sure and save the testp2app.product file (ctrl-s) or your application will fail the next test.

To make sure all of this is working,

From Overview tab, select the Synchronize link
Click the Launch eclipse application link

This will again verify that that the application runs using the specified product configuration.

Exporting

We can now export our application and create a local metadata and artifact repository from the data. To do this we will use the Eclipse Product export wizard available from the product configuration page. (testp2app.product)

From the test2app.product, select export wizard from Export column tab area.
Specify a destination directory (C:\equinox.p2\cosmos
Check the Generate Metadata repository checkbox.
Click Finish.

This will generate a local metatadata and artifact repository in the specified destination directory.

Running ProvAdminUI

We now should have a local repository of the RCP application and all of the bundles necessary to run it. To do the first install we will run the Provisioning Admin UI. It is similar in nature to the tool used to replace the Update Manager available in the Eclipse 3.4 SDK.

To run the admin ui,

Select the Run icon in the toolbar and select the pulldown.
From the displayed available options, select Run Configurations... at the bottom.
From the Run Configurations page, select the OSGI Framework ProvAdminUI. Note that you may need to 
 click the Add Required Bundles button if your application fails to run in the next step.
Click the Run button.

This will run the Admin UI and you should a window displayed to you.

• Specify metadata repository

First we will need to specify the metadata repository. To do this,

Highlight the Metadata Repositories tab.
In the window, right click and select the Add.. button. This will display the Add dialog.
From the dialog, click the Local button and browse to the location specified for the destination in the
 previous Product export step. Be sure and select down and include the repository directory.
Click Ok.
To verify, expand the repository you added and you should see your application (com.eclipse.cosmos.test2papp.product)

• Specify artifact repository

To specify an artifact repository,

Select the Artifact Repositories tab and right click in the window.
In the window, select the Add.. button. This will display the Add dialog.
From the dialog, click the Local button and browse to the location specified for the destination in the
 previous Product export step. (C:\equinox.p2\cosmos\repository) Be sure and select down and include the 
 repository directory.
Click Ok.

To verify, expand the repository you added. You should see all of the bundles we added in the test2app.product configuration step.

• Specify profile

In the Admin UI, the lower window is where you specify Profiles. To create a new profile,

Right click in the window and select Add Profile.
In the dialog,
Specify a unique profile id. (testp2profile)
Specify an install folder. This is where the application will get installed. (C:\equinox.p2\install)
Specify a Bundle pool location. (C:\equinox.p2\install)
Specify a name. (Test P2 Profile)
Click Ok.

• Install our application.

To install our RCP Application (com.eclipse.cosmos.testp2app), we just need to drag and drop the application to profile.

Highlight in the metadata tab your application.
Click then drag and drop it to the profile entry we created (testp2profile)

You will see a Resolving Dependencies dialog pop-up and then disappear quickly. Then you will see an Install window with your application shown and a checkbox beside it. Click Finish.

The ProvAdminUI will now install the application along with any dependent bundles into the specified install area. To verify, browse to the profile directory and run the eclipse.exe there. You should see your RCP application run.

Use the Installer

Along with the ProvAdminUI tool, the p2 source code provides a sample installer that can be used to perform the install operations that the ProvAdminUI tool provides. To use this tool, we will need to do the following.

• Create a run configuration

First, we will create a properties file that the installer will need. Using your favorite editor,

Open a new file called testp2app_installer.properties ( C:\equinox.p2\testp2app_installer.properties)
Place the following in this file.

eclipse.p2.metadata=file:///C:/equinox.p2/cosmos/repository
eclipse.p2.artifacts=file:///C:/equinox.p2/cosmos/repository
eclipse.p2.flavor=tooling
eclipse.p2.profileName=MyCosmosProfile
eclipse.p2.launcherName=eclipse
eclipse.p2.rootId=com.eclipse.cosmos.testp2app
eclipse.p2.autoStart=true

From Eclipse,

Select the Run icon from the toolbar and from the pull down menu select Run Configurations...
Select Run Configuration by highlighting the Eclipse Application tree node and clicking the New icon.
From the Configuration Main tab, select Run a program and from the pulldown, select org.eclipse.equinox.p2.installer.product.
At the top, specify a name. (TestP2Installer)
From the Arguments tab, add the following
-Dorg.eclipse.equinox.p2.installDescription=file:///C:/equinox.p2/testp2app_installer.properties
Click the Apply button.
Click the Run button.

The p2 installer app will now launch and you should get a window displayed. From here, select a directory that you want to install the data from and click Finish.

You should now see the install running and the components being layed down.

Congratulations.