Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Make the library an OSGi bundle (using maven-bundle-plugin) and deploy it to a Maven repository
  2. Aggregate the library into an Eclipse feature, and put it into a p2 repository. We use the textgridlab-dependencies project for that.
  3. Depend on feature in an Eclipse-only feature or the product, and depend on the bundle or its packages in your bundle.

...

In principle, your library can be OSGified by adding specific metadata to its Manifest file. There is a Maven plugin, the maven-bundle-plugin, created in the Apache Felix project and using the bnd bundling tool, that is able to auto-generate the metadata for you. There are two alternative ways to use this plugin:

...

Info
titleMaven vs. OSGi version

Your OSGified bundle will have two versions, and this is bound for trouble since the versioning systems are fundamentally different:

  • a Maven version typically consists of three dot-separated numeric parts with an optional -SNAPSHOT suffix. SNAPSHOT will be replaced with a timestamp when you deploy the snapshot to a repository, you can still reference the latest snapshot using the version string 1.2.3-SNAPSHOT. A released version does not have a suffix, so 1.2.3-SNAPSHOT1.2.3.
  • an OSGi version typically consists of four segments. In Eclipse and Tycho, the last segment can be specified as qualifier in the source, which will be replaced by a timestamp (or an arbitrary override) during build. It is not possible to specify a literal qualifier in a version dependency, however it is not customary to specify four-component-version numbers in dependency, typically a dependency on 1.2.3 will take any (= usually the newest available) version starting with 1.2.3.
    There are different semantics than with the maven SNAPSHOT for OSGi versions: 1.2.3.201312281305 > 1.2.3

 

The Maven version will be used when (plain) Maven is used to resolve the library, e.g., from a Maven repository. The OSGi version is used by, e.g., Eclipse and p2. Note that Felix, as opposed to Tycho, includes a literal SNAPSHOT in the OSGi version number instead of expanding it, making different SNAPSHOTs of the same version indistinguishable for p2. Thus, you should update your snapshots' explicit version numbers if you want to force your plugin to land in the TextGridLab.

Including your library in a feature and in a p2 update site

We maintain a project as part of the TextGridLab build that is used for the transformation from the Maven world to the Eclipse/p2 world – textgridlab-dependencies. This project is integrated in the TextGridLab integration build, and we're using a Jenkins build to deploy its result to a p2 update site from which the other TextGridLab components fetch their dependencies.

Like the other TextGridLab components, textgridlab-dependencies uses the Git Flow model, so please push your commits into the develop branch.

Integrating a new dependency

  1. Add the maven coordinates of your dependency to the dependencies section of textgridlab-dependencies' root POM. Please use a property for the version number.
  2. Add a feature submodule. We'd suggest you copy an existing feature submodule and adjust its names, don't forget to add a modules entry to the root pom.xml. You can also add your dependency to a suitable existing feature.
    • (warning) You SHOULD either use a -SNAPSHOT (pom.xml) / .qualifier (feature.xml) version or you must explicitly increase your feature's version number every time you upgrade the included libraries.
  3. Add a plugin entry for your library to your feature.xml:

    Code Block
    languagexml
    titlefeature.xml excerpt
    linenumberstrue
       <plugin 
           id="info.textgrid.utils.linkrewriter.core"
           download-size="0"
           install-size="0"
           version="0.0.0"
           unpack="false"/>

    The ID ② is the Bundle-Symbolic-Name of the OSGi bundle, it is typically generated by the maven-bundle-plugin using a sensible heuristic. You should use 0 for download-size ③ and install-size ④ as these will by calculated on build. We also recommend to insert 0.0.0 as version ⑤ – this will be replaced by the actual version used on build (and specified by you in the root pom.xml).

  4. Commit and push your changes and watch the integration build.