Build comparison support is an incubating feature. This means that it is incomplete and not yet at regular Gradle production quality. This also means that this Gradle User Guide chapter is a work in progress.
Gradle provides support for comparing the outcomes (e.g. the produced binary archives) of two builds. There are several reasons why you may want to compare the outcomes of two builds. You may want to compare:
A build with a newer version of Gradle than it's currently using (i.e. upgrading the Gradle version).
A Gradle build with a build executed by another tool such as Apache Ant, Apache Maven or something else (i.e. migrating to Gradle).
The same Gradle build, with the same version, before and after a change to the build (i.e. testing build changes).
By comparing builds in these scenarios you can make an informed decision about the Gradle upgrade, migration to Gradle or build change by understanding the differences in the outcomes. The comparison process produces a HTML report outlining which outcomes were found to be identical and identifying the differences between non-identical outcomes.
The following are the terms used for build comparison and their definitions.
In the context of build comparison, a build is not necessarily a Gradle build. It can be any invokable “process” that produces observable “outcomes”. At least one of the builds in a comparison will be a Gradle build.
Something that happens in an observable manner during a build, such as the creation of a zip file or test execution. These are the things that are compared.
The build that comparisons are being made against, typically the build in its “current” state. In other words, the left hand side of the comparison.
The build that is being compared to the source build, typically the “proposed” build. In other words, the right hand side of the comparison.
The Gradle build that executes the comparison process. It may be the same project as either the “target” or “source” build or may be a completely separate project. It does not need to be the same Gradle version as the “source” or “target” builds. The host build must be run with Gradle 1.2 or newer.
Build outcomes that are intended to be logically equivalent in the “source” and “target” builds, and are therefore meaningfully comparable.
A build outcome is uncompared if a logical equivalent from the other build cannot be found (e.g. a build produces a zip file that the other build does not).
A build outcome that cannot be understood by the host build. This can occur when the source or target build is a newer Gradle version than the host build and that Gradle version exposes new outcome types. Unknown build outcomes can be compared in so far as they can be identified to be logically equivalent to an unknown build outcome in the other build, but no meaningful comparison of what the build outcome actually is can be performed. Using the latest Gradle version for the host build will avoid encountering unknown build outcomes.
As this is an incubating feature, a limited set of the eventual functionality has been implemented at this time.
Only support for comparing Gradle builds is available at this time.
Both the source and target build must execute with Gradle newer or equal to version 1.0.
The host build must be at least version 1.2.
Future versions will provide support for executing builds from other build systems such as Apache Ant or Apache Maven, as well as support for executing arbitrary processes (e.g. shell script based builds)
Only support for comparing build outcomes that are zip archives is supported at this time.
This includes jar, war and ear archives.
Future versions will provide support for comparing outcomes such as test execution (i.e. which tests were executed, which tests failed, etc.)
The compare-gradle-builds plugin can be used to facilitate a comparison between two Gradle builds. The plugin
adds a CompareGradleBuilds task named “compareGradleBuilds”
to the project. The configuration of this task specifies what is to be compared. By default, it is configured to compare the current build with itself
using the current Gradle version by executing the tasks: “clean assemble”.
apply plugin: 'compare-gradle-builds'
This task can be configured to change what is compared.
compareGradleBuilds {
sourceBuild {
projectDir "/projects/project-a"
gradleVersion "1.1"
}
targetBuild {
projectDir "/projects/project-b"
gradleVersion "1.2"
}
}The example above specifies a comparison between two different projects using two different Gradle versions.
You can use the build comparison functionality to very quickly try a new Gradle version with your build.
To try your current build with a different Gradle version, simply add the following to the build.gradle of the root project.
apply plugin: 'compare-gradle-builds'
compareGradleBuilds {
targetBuild.gradleVersion = "«gradle version»"
}Then simply execute the compareGradleBuilds task. You will see the console output of the “source” and “target” builds as they are executing.
If there are any differences between the compared outcomes, the task will fail. The location of the HTML report providing insight into the comparison will be given. If all compared outcomes are found to be identical, and there are no uncompared outcomes, and there are no unknown build outcomes, the task will succeed.
You can configure the task to not fail on compared outcome differences by setting the ignoreFailures property to true.
compareGradleBuilds {
ignoreFailures = true
}For an archive to be a candidate for comparison, it must be added as an artifact of the archives configuration. Take a look at Chapter 52, Publishing artifacts for more information on how to configure and add artifacts.
The archive must also have been produced by a Zip, Jar,
War, Ear task. Future versions of Gradle
will support increased flexibility in this area.