As the name implies, Installable Units (IUs for short) describe things that can be installed, updated or uninstalled. They do not contain the actual artifacts but rather essential information about such artifacts (e.g., names, ids, version numbers, dependencies, etc) and are not aware about what they deliver. They describe things. They are NOT the things. So for example an IU for a bundle is NOT the bundle. The bundle is an "artifact". The metadata allows dependencies to be structured as graphs without forcing containment relationships between nodes. Here is detailed presentation of what an installable unit is made of.
An IU is uniquely identified by an ID and a version.
IU dependencies and capabilities
In the same way bundles have import and export packages, IUs have dependencies to talk about their prerequisites and provide capababilities to tell other what they offer. The capabilities are expressed in generic term. When a capability is provided, it is done in the context of a namespace, under a specific name and version. Dependencies are expressed against those capabilities to express all the requirements of an IU. This approach offers great flexibility to express dependencies.
For example, an IU representing an OSGi bundle could provide as capabilities the packages it exports and the services it registers at runtime.
java.packages, com.acme.bar, 1.0.0 java.packages, com.acme.foo, 1.2.3 osgi.services, com.acme.myservice, 2.0.0
And it could require other packages and services.
java.packages, org.apache.xerces, [1.0.0, 2.0.0) osgi.services, org.sax.parsing.service, [1.0.0, 1.0.3)
Note that the id of the IU is also exposed as a capability in the org.eclipse.equinox.prov.iunamespace.
These dependencies information are used by the agent to decide what needs to be installed. For example if you are installing the org.eclipse.jdt.ui IU, the dependencies expressed will cause the transitive closure of IUs reachable to be installed.
The IU does not deliver any content. Instead it refers to artifacts. The artifacts are mirrored from an artifact server into a local artifact server on the request of touchpoints. Note that this area is still under work as other concepts such as validation support have to be added.
Touchpoint, touchpoint data
The touchpoint data contains touchpoint specific data that will be used to apply the software lifecycle (install, uninstall, update, configure, etc).
Installable Unit fragments
Installable unit fragments are installable units that complement an existing installable unit. When a fragment applies to an installable unit, it is being attached to this installable unit. A fragment can apply to multiple installable unit. Once the fragment has been attached its content is seamlessly accessible from the installable unit.
An installable unit fragment can not modify the dependencies of the installable unit to which it is attached.
Installable unit fragments are used to deliver touchpoint data common to multiple installable unit. It should also be used to deliver metadata translation.
Installable unit best practices
The information contained in an installable unit must be kept generic to allow for reuse. For example, the org.eclipse.equinox.common bundle needs to be started. However the start level at which it needs to be started differs based on the scenario where the bundle is being used (e.g. in a RCP context, it needs to be started at level 2, whereas it needs to be started at level 3 in the server side context).
Therefore for the IU to stay generic the touchpoint data for org.eclipse.equinox.common can not specify a start level. The IU should only contain information related to the dependencies and capabilities that the IU has.
In order to deliver the start level information, installable unit fragments will be created. In our example we would have one installable unit fragment to be used in an RCP Context and another one for the server side context. Each of these IU fragments will have its own unique ID and will not collide with each others.