xebialabs/gradle-xl-dependency-plugin

XebiaLabs Gradle dependency management

Gradle XebiaLabs Dependency Management Plugin

This is the Gradle XebiaLabs Dependency Management plugin. When applied to your Gradle project it will be possible to omit version numbers from the specified dependencies, and have them come from imported dependency specification files.

How to apply

This plugin is not published (yet) to Gradle Plugin Central. It is only available from our Nexus. Please apply the plugin using the following code in the rootProject build.gradle file.

rootProject build.gradle

buildscript {
  repositories {
    maven {
        url "${nexusBaseUrl}/repositories/releases"
        credentials {
            username nexusUserName
            password nexusPassword
        }
    }
  }

  dependencies {
    classpath "gradle.plugin.com.xebialabs:gradle-xl-dependency-plugin:1.0.0"
  }

  apply plugin: 'com.xebialabs.dependency'
}

Plugins contained

The 'com.xebialabs.dependency.base' plugin

This plugin is the base plugin that doesn’t force any opinions on the project. Note this plugin can only be applied on the rootProject

What it does

When applied the plugin does the following:

• An extension named dependencyManagement is added to the rootProject

• The resolutionStrategy of allProjects.configurations is set to resolve versions against this plugin

The 'com.xebialabs.dependency' plugin

This plugin builds on top of the com.xebialabs.dependency.base plugin, and adds the following opinions on top of the xebialabs.dependency.base plugin:

1. It will take any overridden versions defined on the rootProject (See: Version keys as project properties)

2. It will load a ${rootProject.projectDir}/gradle/dependencies.conf file which is required to be present

How it works

Using the dependencyManagement extension it is possible to import configuration files containing dependency information.

• You can either import a file local to the project

• You can import a maven dependency using the shortform (<group_id>:<artifact_id>:<version>) dependency notation. In this case the plugin will attempt to find the <artifact_id>.conf file located at that location in the maven repository.

For example:

build.gradle example

apply plugin: 'java'
apply plugin: 'xebialabs.dependency'

dependencyManagement {
  importConf rootProject.file("path/to/hocon.conf")
  importConf "com.xebialabs.xl-platform:xl-reference:${xlPlatformVersion}"
}

repositories {
  mavenCentral()
}

dependencies {
  compile "org.apache.pekko:pekko-actor_$scalaVersion"
  testCompile "junit:junit"
}

The file format

The plugin reads the dependency management specification from a HOCON file. Substitutions are allowed inside one file, not across multiple files. The format of the HOCON file should be the following:

reference.conf

dependencyManagement {
  versions {
    junitVersion: "4.12"
    scalaVersion: "2.11"
    akkaVersion: "2.3.9"
  }
  dependencies: [
    "junit:junit:$junitVersion"
    {
      group: "com.typesafe.akka"
      version: "$akkaVersion"
      artifacts: [
        "akka-actor_$scalaVersion"
        "akka-testkit_$scalaVersion"
      ]
    }
  ]
  rewrites {
    "jdom:jdom": "org.jdom:jdom"
  }
  blacklist: [
    "com.google.collections:google-collections"
  ]
}

As is shown, there are 4 sections in the conf file.

The 'versions' section

The versions section allows you to refer to a version number using a name. In this way you can (potentially) reuse a single version number for different related artifacts. It is a map of key-value pairs.

The 'dependencies' section

The dependencies section is a list of dependencies in either:

• <group_id>:<artifact_id>:<version> notation

• a block containing a group of similar artifacts sharing a group_id and version

The placeholders in the strings will be replaced with the data coming from the versions section. Each matching dependency in each configuration of each project will be forced to use the version defined in this block.

The 'rewrites' section

The rewrites section contains group:artifact pairs that should be rewritten to a different group:artifact combination. This allows to map moved modules onto their new location.

The 'blacklist' section

The blacklist section contains group or group:artifact entries. All entries listed here will be blacklisted from all configurations of all projects.

Advanced use

Version keys as project properties

It is possible to define named versions using project properties. The project property should be of the format: dependencyManagement.versions.<name> in order to be picked up. See for instance the following example:

reference.conf

dependencyManagement {
  versions {
    junitVersion: "4.12"
  }
  dependencies: [
    "junit:junit:$junitVersion"
  ]
}

build.gradle

apply plugin: 'com.xebialabs.dependency.base'
apply plugin: 'java'

dependencyManagement {
  supplier com.xebialabs.gradle.dependency.supplier.ProjectSupplier(project)
  importConf project.file('reference.conf')
}

dependencies {
  testCompile 'junit:junit'
}

If you would launch gradle now using the following command line: gradle build -PdependencyManagement.versions.junitVersion=4.11, it would force junit to the 4.11 version instead of the 4.12 specified in the reference.conf file.

The com.xebialabs.dependency plugin takes care of this automatically.

Adding your own supplier

It is possible to add your own DependencyManagementSupplier that will supply the dependency management information to the plugin. You can do so by extending the com.xebialabs.gradle.dependency.supplier.DependencyManagementSupplier.

You can add your own supplier to your build.gradle file using the following snippet:

build.gradle

apply plugin: 'com.xebialabs.dependency.base'

dependencyManagement {
  supplier <your class>
}