What is the first thing that you would expect to do with some provisioning code - install something, of course! This section is to guide you through a happy-path using equinox provisioning to install an Eclipse SDK.
There are four basic concepts that will help you understand the install:
- Agent - the program that will perform the install. In general, the provisioning agent could appear in various forms - a standalone application, a silent install demon, a perspective in the ide. We will use the Admin UI application to do our install.
- Metadata - the information about what can be installed. The metadata is used by the agent to analyze dependencies and perform the installation steps. Metadata lives in one or more repositories.
- Artifacts - the actual bits that will be installed. There are various kinds of artifacts that are processed differently during the install. Associated metadata determines how a given artifact is processed. Artifacts live in one or more repositories. The metadata and artifacts generally come from different repositories and may be widely distributed.
- Profile - in the most simple form, a profile is the location where the bits will be installed. The term 'profile' is not a very good term and probably will disappear from end user concepts (there's a bug about this), but it is the term we are using for now.
Steps to using the agent
In this example, we will be installing a 3.4M1 SDK. The current agent only supports Windows but M2 should see us building and testing on a wider range of platforms.
Step 1 - Exploring the agent
The Admin agent application is available from the Equinox download site - click the link and you should see (Firefox)
The zip file is ~15 MB. Download it and unzip it anywhere on a writable local drive. The result of this step is that you will have a directory (equinox.prov) containing the agent:
Step 2 - Exploring the agent
Double-click on the eclipse.exe and the Admin UI will come up. It looks something like (resized to fit here):
Note that you see here all four concepts:
- Agent - the main window.
- Metadata - the exposed Metadata Repositories view.
- Artifacts - the hidden Artifact Repositories view.
- Profiles - the Profiles view.
The Metadata Repositories view is empty, so first let's add a repository on eclipse.org which contains metadata for the Eclipse SDK, and other goodies. You can do this from the popup menu in the Metadata Repositories view.
You'll see a dialog that lets you add a URL (or a local directory or jar file). We're going to use a test update site on eclipse.org. (This may take awhile, we're working on the performance here)...
Once the repository has been added, you should see something like this:
The Profiles view shows the Equinox Provisioning UI profile. This is the profile defining the install location for the Admin UI app you are running. If you right click on the list item and select properties, you will see some information about this profile:
If a Metadata repository or a Profile is not empty, then you can expand it to see the installable units (which are really installed units) in the profile. A preference is available to show only the installable units which are a Group; the default for this preference is true. Expanding to show the groups will give you something like this:
Now, we'll switch to the Artifact Repositories view. It is empty because you have not yet added an artifact repository.
The metadata repository you added describes what software is available, while the artifact repository contains the actual software that will be downloaded. These repositories don't have to be located at the same URL, but they can be.
The server on eclipse.org has the metadata and artifacts in the same location, so you can add an artifact repository using the same URL we used for the metadata repository (by using the popup menu in the Artifact Repositories view). Once the repository has been added, you should see the actual artifacts in the Artifact Repository view:
Step 3 - Creating a new profile
You will need to decide where you want to install the SDK and create a profile for that location. In the profile view, right click and select 'Add a new profile':
then fill in the appropriate data in the Profile properties dialog:
The meaning of the Flavor property is an advanced topic, so don't play with that unless you want to explore error conditions! In fact, once it has been set in a profile and something has been installed using that flavor, the Flavor property should be non-modifiable (bug).
Step 4 - Doing the install
The sdk group is near the bottom of the list of group installable units in the repository, so scroll down until sdk is in view. There may be multiple versions of the sdk available. If so, find the one you are interested in.
The Admin UI supports two ways of initiating an install: 1). you can right click on the sdk group, select Install..., then choose the profile in the resulting popup dialog; or 2). you can drag&drop the sdk group onto the profile. Let's do d&d since it is easier (the little smudge over SDK is the drop cursor):
You will see a progress indicator while the agent figures out what needs to be downloaded.
Next, you will be shown more detail about what is to be installed, such as the size of the artifacts needed. (We'll be showing more information here, such as license information or detail).
Click the install button, and the install will start (assuming you have network connectivity org.eclipse.download, no firewall issues, etc):
Anecdotally, the install takes slightly less time than the download of a corresponding Eclipse SDK zip (one datapoint: 21 minutes for equinox provisioning install vs. 23 minutes for download of the zip).
Step 5- After the install
The install will finish with a whimper, not a bang, as the progress dialog disappears and the new profile you created is populated with the groups and installable units that are now installed into the profile:
The directory you chose for your profile location will look like this, before running the eclipse you just installed:
Step 6- Installing the end user UI
The Agent UI is really intended for system administrators and power users who want to browse and manage the applications they have installed. A typical end user of an Eclipse-based application doesn't want to be exposed to all these concepts of metadata, artifacts, profiles, and IUs. They just want to install, run, and update their software. For this purpose, there is a p2-based end user UI intended for dropping into an Eclipse application. Once you have installed the SDK, you can install this end-user UI by dragging the "End User UI" group from the metadata repository into the profile that you just installed the SDK into. Now, when you start up the SDK, there will be a new menu entry (Help > Software Updates (Incubation), that you can use to manage and update the running application.
If you encounter bugs, or would like to enter enhancement requests for this work, please use the Equinox Incubator category in Bugzilla. You can add the prefix "[prov]" to the subject line of the bug report to help us with bug triage.
For more detailed information, visit one or more of the following pages:
- Equinox p2 Top level site for the provisioning work going on in Equinox.
- Equinox p2 Admin UI Users Guide For folks who want experiment with the equinox capabilities for installing, updating, fixing, and uninstalling capabilities.
- Equinox p2 Console Users Guide For OSGI geeks who enjoy starting and stopping bundles.
- Equinox p2 Getting Started for Developers For developers who want to create applications that extend or exploit equinox provisioning.