Gradle-based Eclipse plugin build

Refactoring out build sources from Buildship into a Gradle plugin to reuse in other Eclipse plugin projects.

Status

Except organizing a Gradle build this project so far does not contain original work of ours, code base was taken from here, git repo migrated and pruned: https://github.com/eclipse/buildship/tree/master/buildSrc/

This documentation is work in progress, and originally obtained from the Buildship too: original Usage.md, original stories/Build.md.

We use eclipsebuild plugin internally at i:FAO for building our own Eclipse plugins.

Usage

Building

Buildship is built using a set of plugins that support dependency resolution, processing Eclipse descriptors, and publishing Eclipse update sites. The scripts for the plugins are located in the buildSrc folder.

The plugin scripts in buildSrc expect a small set of Eclipse bundles/libraries in the buildSrc/libs folder that are committed to the Git repository to avoid bootstrapping problems. All plugins are defined in the eclipsebuild package.

The plugin version is specified in the version.txt file.

Plugin set overview	comment
org.eclipse.buildship.build.build-definition-plugin	applied to multi-module ROOT project
org.eclipse.buildship.build.bundle-plugin	applied to OSGi bundle subprojects
org.eclipse.buildship.build.test-bundle-plugin	applied to test bundle subprojects
org.eclipse.buildship.build.feature-plugin	applied to a Eclipse feature subproject
org.eclipse.buildship.build.update-site-plugin	applied to a subproject that generates a p2 update site for features/plugins

build-definition-plugin

The build-definition-plugin Gradle plugin has to be applied on the root project. It defines the target platform for the build and makes all Eclipse plugins available for dependency resolution. The BundlePlugin, FeaturePlugin, and UpdateSitePlugin Gradle plugins all depend on the tasks provided by the BuildDefinitionPlugin.

The set of supported target platforms are declared in the root build.gradle file. For example:

    apply plugin: org.eclipse.buildship.build.build-definition-plugin
    
    eclipseBuild {
        defaultEclipseVersion = '44'
    
        targetPlatform {
            eclipseVersion = '44'
            targetDefinition = file('tooling-e44.target')
            versionMapping = [
                'org.eclipse.core.runtime' : '3.10.0.v20140318-2214'
            ]
        }
    
        targetPlatform {
             eclipseVersion = '43'
             ...
         }
     }

When running a Gradle build using the above configuration, the build uses the Eclipse target platform version 44. The build can use an alternative target platform by specifying the eclipse.version Gradle project property. For example:

    gradle build -Peclipse.version=43

The contributed task installTargetPlatform creates the target platform. It does the following:

1. Downloads an Eclipse SDK in the specified version
2. Installs the specified features defined in the target definition file
3. Converts all plugins from the downloaded Eclipse SDK into a Maven repository

Once the 'mavenized' target platform is available, the Gradle build configuration can reference Eclipse plugin dependencies like any other dependency. The groupId is always eclipse. For example:

    compile 'eclipse:org.eclipse.jdt.ui:+'

By default, the location of the generated target platform is ~/.tooling/eclipse/targetPlatforms. The location can be customized by specifying the targetPlatformsDir Gradle project property:

    gradle installTargetPlatform -PtargetPlatformsDir=/path/to/target/platform

The versionMapping can be used to define exact plugin dependency versions per target platform. A bundle can define a dependency through the {@code withEclipseBundle()} method like

    compile withEclipseBundle('org.eclipse.core.runtime')

If the active target platform has a version mapped for the dependency then that version is used, otherwise an unbound version range (+) is applied.

bundle-plugin

The bundle-plugin Gradle plugin knows how to build Eclipse plugins and needs to be applied on the plugin project(s). The plugin creates a jar file containing all elements defined in the feature project's build.properties. The bundle manifest file META-INF/MANIFEST.MF is copied into the generated jar file and the version is replaced with the one from the current build.

The BundlePlugin also adds the capability to bundle jars along with the dependencies from the target platform. This can be achieved by declaring bundled dependencies. For example:

    apply plugin: org.eclipse.buildship.build.bundle-plugin
    
    dependencies {
        compile 'eclipse:org.eclipse.core.runtime:+'
        bundled 'com.google.guava:guava:18.0'
    }

The dependencies of the bundled configuration are used by the updateLibs task. This task downloads the transitive dependencies into the lib folder, updates the manifest file to reference these dependencies and updates the .classpath file.

test-bundle-plugin

The test-bundle-plugin Gradle plugin is an extension of the bundle-plugin and knows how to run tests. For example:

    apply plugin: org.eclipse.buildship.build.test-bundle-plugin
    
    eclipseTest {
        fragmentHost 'org.eclipse.buildship.core'
        applicationName 'org.eclipse.pde.junit.runtime.coretestapplication'
        optionsFile file('.options')
    }

The plugin adds a task called eclipseTest. This task does the following:

1. Clears the buildDir/eclipseTest folder in order to have a clean environment for testing.
2. Copies the non-mavenized target platform to the buildDir/eclipseTest folder.
3. Installs the project dependency plugins into the target platform with the P2 director.
4. Executes the target platform and runs the tests with a custom Gradle test runner (which is an ITestRunListener implementation).

Currently all concrete classes are gathered by the test plugin for test execution. The test results are collected in the build/reports folder.

The implementation uses techniques defined in the article PDE Unit Tests using Ant.

feature-plugin

The feature-plugin Gradle plugin knows how to build an Eclipse feature and needs to be applied on the feature project(s). The plugin creates a jar file containing all elements defined in the feature project's build.properties.

update-site-plugin

The update-site-plugin Gradle plugin knows how to build an update site and needs to be applied on the site project. The plugins adds a task called createP2Repository. This task takes all project dependencies and, if they are either Eclipse plugins or Eclipse features, publishes them to a local P2 repository. The generated repository is available in the build/repository folder. For example:

    apply plugin: org.eclipse.buildship.build.update-site-plugin
    
    updateSite {
        siteDescriptor = file('category.xml')
        extraResources = files('epl-v10.html', 'readme.txt')
        p2ExtraProperties = ['p2.mirrorsURL' : 'http://www.eclipse.org/downloads/download.php?file=/path/to/repository&format=xml' ]
        signBundles = true
    }

The siteDescriptor should point to a category descriptor which is used to publish update sites. The extraResources allows to reference extra resources to add to the update site. The p2ExtraProperties allows to add properties elements to the update site's artifacts.xml file under the repository/properties node. The signBundles specifies whether the artifacts of the update site should be signed (default is false).

Adding a new Eclipse plugin

• Create a new folder under the buildship root folder
• Create a project in that folder through Eclipse and use the same name for the project as for the folder
• Create a build.gradle file and apply the BundlePlugin
• Add the project to the settings.gradle file

Building/deployin this Gradle plugin

$ ./gradlew clean build

$ ./gradlew build bintrayUpload -Duser=<bintray_user> -Dkey=<bintray_key>

Credits

Credits go to:

• Donát Csikós, Eclipse Buildship project, Eclipse Foundation and Gradle Inc.
• our employer i:FAO - an amadeus group company

License

The project is licensed under the Eclipse Public License 1.0.