Home

Awesome

Unpuzzle logo

Build Status Maintainer Status Release Snapshot License

Unpuzzle is a set of tools for mavenizing OSGi-bundles. You can consume Unpuzzle in two forms: as a gradle plugin and as an ordinary jar-library. All versions of Unpuzzle are available at jcenter and maven-central under the group 'org.akhikhl.unpuzzle'.

Content of this document

  1. What "mavenizing" means?
  2. Gradle plugin
  3. Gradle tasks
  1. Configuration DSL
  2. uploadEclipse configuration
  3. Configuration hierarchy
  4. Support of multiple Eclipse versions
  5. Jar-library API
  6. Copyright and License

What "mavenizing" means?

When OSGi-bundle is being "mavenized", the following happens:

As the result, you get complete and consistent representation of OSGi-bundles as a set of maven artifacts with dependencies. Combined with maven or gradle, it can greatly simplify building OSGi/eclipse applications.

Gradle plugin

Add the following to "build.gradle":

apply from: 'https://raw.github.com/akhikhl/unpuzzle/master/pluginScripts/unpuzzle.plugin'

then do "gradle installEclipse" from command-line. This will download eclipse from it's distribution site and install eclipse plugins to the local maven repository: $HOME/.m2/repository, into maven group "eclipse-kepler".

Alternatively, you can download the script from https://raw.github.com/akhikhl/unpuzzle/master/pluginScripts/unpuzzle.plugin to the project directory and include it like this:

apply from: 'unpuzzle.plugin'

or feel free copying (and modifying) the declarations from this script to your "build.gradle".

Gradle tasks

downloadEclipse

downloadEclipse task downloads and unpacks distribution of the selected Eclipse version from the official site into directory $HOME/.unpuzzle.

By default Unpuzzle downloads eclipse kepler SR1, delta-pack and eclipse-SDK. You can fine-tune, which version of eclipse is downloaded and with which add-ons by providing your own configuration.

Before downloading a distribution package this task compares file size to the one returned by HTTP HEAD request. If file size did not change, no download is performed.

Hint: you can force re-download of eclipse distribution simply by deleting *.zip and *.tar.gz files in the directory $HOME/.unpuzzle/downloaded.

installEclipse

installEclipse task mavenizes all OSGi-bundles of selected Eclipse version and installs the generated maven artifacts to local maven repository ($HOME/.m2/repository).

By default all OSGi-bundles are installed into "eclipse-kepler" maven group. You can define other maven group by providing your own configuration.

installEclipse task depends on [downloadEclipse](#downloadeclipse] task.

uninstallEclipse

uninstallEclipse task uninstalls installed OSGi-bundles of the selected Eclipse version from the local maven repository ($HOME/.m2/repository).

uninstallAllEclipseVersions

uninstallAllEclipseVersions task uninstalls installed OSGi-bundles of all Eclipse versions from the local maven repository ($HOME/.m2/repository).

uploadEclipse

uploadEclipse task mavenizes all OSGi-bundles of the downloaded eclipse distribution and installs the generated maven artifacts to remote maven repository.

You should specify [uploadEclipse configuration](#uploadEclipse-configuration] in order to make uploadEclipse work.

By default all OSGi-bundles are installed into "eclipse-kepler" maven group. You can define other maven group by providing your own configuration.

uploadEclipse task depends on [downloadEclipse](#downloadeclipse] task.

purgeEclipse

purgeEclipse task cleans everything specific to Unpuzzle plugin. Particularly, it uninstalls installed maven artifacts and deletes directory $HOME/.unpuzzle.

Configuration DSL

Unpuzzle works without configuration out of the box. You just apply gradle plugin, run installEclipse task and Unpuzzle does it's job with reasonable defaults.

However, there are cases when you need to fine-tune Unpuzzle. For example you might want to download/install another version of eclipse distribution.

Unpuzzle supports the following configuration DSL:

unpuzzle {

  localMavenRepositoryDir = new File(System.getProperty('user.home'), '.m2/repository')

  unpuzzleDir = new File(System.getProperty('user.home'), '.unpuzzle')

  selectedEclipseVersion = '4.3.2'

  eclipseVersion('4.3.2') {

    eclipseMavenGroup = 'eclipse-kepler'

    eclipseMirror = 'http://mirror.netcologne.de'

    eclipseArchiveMirror = 'http://archive.eclipse.org'
    
    sources {

      source "$eclipseMirror/eclipse//technology/epp/downloads/release/kepler/SR2/eclipse-jee-kepler-SR2-linux-gtk-x86_64.tar.gz"
      source "$eclipseMirror/eclipse//eclipse/downloads/drops4/R-4.3.2-201402211700/eclipse-SDK-4.3.2-linux-gtk-x86_64.tar.gz", sourcesOnly: true
      source "$eclipseMirror/eclipse//eclipse/downloads/drops4/R-4.3.2-201402211700/eclipse-4.3.2-delta-pack.zip"
      
      languagePackTemplate '${eclipseMirror}/eclipse//technology/babel/babel_language_packs/R0.11.1/kepler/BabelLanguagePack-eclipse-${language}_4.3.0.v20131123020001.zip'
      
      languagePack 'de'
      languagePack 'fr'
      languagePack 'es'
    }
  }

  uploadEclipse = [
    url: 'http://example.com/repository',
    user: 'someUser',
    password: 'somePassword'
  ]  
}

Additionally the following properties are injected into version-specific configuration and can be used for calculating correct version of eclipse to download:

You can see the complete and working Unpuzzle configuration here

uploadEclipse configuration

In order to upload mavenized OSGi bundles to remote repository you need to specify three parameters: remote repository URL, user name and password. All three can be specified in one of three places, in the following priority order:

unpuzzle {
  // ...
  uploadEclipse = [
    url: 'http://example.com/repository',
    user: 'someUser',
    password: 'somePassword'
  ]
}

ext {
  // ...
  uploadEclipse = [
    url: 'http://example.com/repository',
    user: 'someUser',
    password: 'somePassword'
  ]
}

projectsEvaluated {
  rootProject.ext {
    uploadEclipse = [
      url: 'file:///home/ahi/repository',
      user: 'someUser',
      password: 'somePassword'
    ]
  }
}

It is probably not good idea to store sensitive information (like user names and passwords) within the source code of your project. Consider: if you store the source code in the version control system, everybody authorized to see the sources effectively gets he credentials to upload to your maven repository.

A healthy decision would be to use the last option - store user name and password in "init.gradle" script outside of the project. See more information about init scripts in official gradle documentation.

Configuration hierarchy

Unpuzzle configurations are hierarchical. That is: when both parent and child project are facilitated with Unpuzzle extension (i.e. when unpuzzle-plugin is included in both), child's extension inherits properties from parent's extension. Child project's extension may override or append individual properties of parent project's extension.

The following properties are overridden rather then appended:

The following properties are appended rather then overridden:

Examples of hierarchical configurations are given in ConfigHierarchyTest.groovy unit-test.

Support of multiple Eclipse versions

Unpuzzle supports Eclipse versions 4.5, 4.4.2, 4.4.1, 4.4, 4.3.2, 4.3.1, 4.2.2, 4.2.1, 3.7.2, 3.7.1 out of the box. You can easily switch between Eclipse versions by simply specifying eclipse version in "build.gradle":

unpuzzle {
  selectedEclipseVersion = '3.7.1'
}

Distribution packages for these versions are predefined in internal script defaultConfig.groovy. This script is always loaded as an implicit ancestor for Unpuzzle configuration.

You are not restricted to using only the designated versions of Eclipse. Any other Eclipse versions (and any additional packages to them) could be configured in "build.gradle" using the same syntax.

Jar library API

Gradle plugin might be sufficient for the most use-cases requiring mavenizing OSGi-bundles. However, you can mavenize OSGi-bundles even without gradle plugin, just by using Unpuzzle API functions.

Good example of Unpuzzle API usage is givenhere.

Essentially, Unpuzzle API consists of four classes:

Copyright and License

Copyright 2014-2015 (c) Andrey Hihlovskiy and contributors.

All versions, present and past, of Unpuzzle are licensed under MIT license.