Spring IO Plugin
Overview
Provides additional checks to ensure Spring IO Platform compatibility
Quick Start
See repo.spring.io to determine the latest available version. Then configure the plugin in your project as follows:
buildscript {
repositories {
maven { url 'https://repo.spring.io/plugins-release' }
}
dependencies {
classpath 'io.spring.gradle:spring-io-plugin:0.0.6.RELEASE'
}
}
// ...
configure(allprojects) {
if (project.hasProperty('platformVersion')) {
apply plugin: 'spring-io'
// necessary to resolve the Spring IO versions (which may include snapshots)
repositories {
maven { url "https://repo.spring.io/libs-snapshot" }
}
dependencyManagement {
springIoTestRuntime {
imports {
mavenBom "io.spring.platform:platform-bom:${platformVersion}"
}
}
}
}
}
Note
|
It is unlikely you will want to apply the plugin or snapshot repository to all projects. This is particularly true if you have sample projects within your project. Instead, you should limit the plugin to modules that are part of the Spring IO Platform. |
Now you can run the following:
$ ./gradlew clean springIoCheck -PplatformVersion=1.0.0.BUILD-SNAPSHOT
This will execute tasks that:
-
Check that Spring IO contains versions for all direct dependencies, all transitive dependencies, or both. For more information refer to the description of the task
-
Ensure that all dependency exclusions use both the group and the module. For more information refer to the description of the task
-
Verify that certain dependencies are not used and suggest alternatives if they are. For more information refer to the description of the task
Alternatively, you can run the following:
$ ./gradlew clean springIoCheck -PplatformVersion=1.0.0.BUILD-SNAPSHOT -PJDK8_HOME=<jdk8-home> -PJDK7_HOME=<jdk7-home>
In addition to the steps listed above this will execute tasks that:
-
Run tests against your compiled code using JDK7 and JDK8 and the Spring IO dependency versions. For more information refer to Additional Tests
If you have any customizations to your test task, you will want to ensure you customize the newly added springIoJdk7Test and springIoJdk8Test tasks. An example of configuring every test to have a specific system property can be seen below:
project.tasks.withType(Test).all {
systemProperty 'some.prop', 'value'
}
If you would like springIoCheck to be invoked when you run ./gradlew build
, then you can make the check task depend
on springIoCheck as shown below:
configure(allprojects) {
apply plugin: 'spring-io'
// ...
check.dependsOn springIoCheck
}
Typically users will keep the springIoCheck task separate so as to only run the springIoCheck task on the CI server.
Spring IO dependencies
The plugin creates a new configuration, springIoTestRuntime
, that contains all of the project’s dependencies with
their versions mapped to those that are in the Platform. This configuration is used when running the additional
tests. The versions in this configuration are managed via the dependency management plugin that is configured to
import the Platform’s bom. For example:
dependencyManagement {
springIoTestRuntime {
imports {
mavenBom "io.spring.platform:platform-bom:${platformVersion}"
}
}
}
The use of a property for the version, and requiring that property to be supplied on the command line, prevents there being a circular dependency between a project that’s part of the Platform and the Platform itself. This allows us to easily check out a particular version of a project and test it against any version of the Platform.
You can use Gradle’s built-in dependencies
task to see details of the springIoTestRuntime
configuration and
the versions that it contains. For example:
$ ./gradlew clean project-name:dependencies --configuration springIoTestRuntime
Overriding versions
To override versions you can declare additional dependency management, or override a property when importing the Platform’s bom. For example:
dependencyManagement {
springIoTestRuntime {
imports {
mavenBom("io.spring.platform:platform-bom:${springIoVersion}") {
bomProperty "mockito.version", "1.10.9"
}
}
}
}
Additional Tests
One of the goals of the Spring IO Platform is to ensure modules work with JDK7 and JDK8 and that they run with specific versions of dependencies. Applying the plugin will create tests that:
-
Ensure that the Spring IO versions of dependencies are used at runtime for the additional test tasks
-
Run against the specified JDKs
For example, the following will compile the project with the declared dependency versions and JDK. It will then run all the tests against JDK7 and JDK8 with the Spring IO dependency versions.
$ ./gradlew springIoCheck -PJDK7_HOME=/opt/java/jdk/Sun/7.0 -PJDK8_HOME=/opt/java/jdk/Sun/8.0
Note
|
You can also place JDK8_HOME and JDK7_HOME in your gradle.properties |
JDK8_HOME
is the absolute path to the JDK8 Home and JDK7_HOME
is the absolute path to the JDK7 Home. The
example above works with the Spring Bamboo environment.
Please note that nothing changes for how your code is actually compiled or consumed by users (dependency changes and JDK changes only impact the additional tests). Also, if JDK7_HOME and JDK8_HOME are both omitted then no additional test tasks will be created .
Sub-tasks
The plugin adds a number of tasks to your build. These are documented below.
springIoIncompleteExcludesCheck
This task ensures that any dependency exclusions that are done use both the group and the module because otherwise the dependency will not be excluded in the generated pom.xml file. For example the following is not allowed because it only excludes the module:
dependencies {
compile('org.springframework:spring-core:3.2.0.RELEASE') {
exclude module: 'commons-logging'
}
}
the following is not allowed because it only excludes the group:
dependencies {
compile('org.springframework:spring-core:3.2.0.RELEASE') {
exclude group: 'commons-logging'
}
}
the following is allowed because it excludes both the group and the module:
dependencies {
compile('org.springframework:spring-core:3.2.0.RELEASE') {
exclude group: 'commons-logging', module: 'commons-logging'
}
}
springIoAlternativeDependenciesCheck
This task will ensure certain dependencies are not used and suggest alternatives. For example, intead of using asm:asm it is preferred to use spring-core’s repackages asm dependencies.
springIoDependencyVersionMappingCheck
This task will check that every dependency in a configuration can be mapped to a dependency that’s part of the
Spring IO Platform. By default, the task will perform this check against the runtime
configuration. The build will
fail if unmapped direct dependencies are found, but unmapped transitive dependencies will not cause a failure. All
three options can be configured:
springIoDependencyVersionMappingCheck {
configuration = configurations.testRuntime
failOnUnmappedDirectDependency = true
failOnUnmappedTransitiveDependency = true
}
configuration
determines the configuration that is checked. failOnUnmappedDirectDependency
controls whether or not
the build will fail if a direct dependency is encountered that is not part of the Spring IO plaform. The default is
true
. failOnUnmappedTransitiveDependency
controls whether or not the build will fail if a transitive dependency is
encountered that is not part of the Spring IO Platform. The default is false
.
Dealing with unmapped dependencies
If you encounter an unmapped dependency, the Platform team can help. First of all, please check for an existing issue. If you find one, add a comment to note your need for the dependency. If there is no existing issue, please open one, providing details of the dependency and the project that requires it.