Monday, January 6, 2014

Identifying Gradle Conventions

Configuration by convention has many advantages, especially in terms of conciseness because developers do not need to explicitly configure things that are implicitly configured through convention. When taking advantage of configuration by convention, however, one needs to be aware of the conventions. These conventions might be documented, but I always like it when I can programmatically determine the conventions because documentation can become outdated (same principle behind code always being correct and comments only sometimes being correct). I begin this post by looking at how to identify the specific conventions associated with the Gradle Java Plugin. I then generalize this approach to identify all properties associated with all tasks associated with the root project of a Gradle build.

The Gradle documentation on Gradle Plugins states the following regarding the importance of Gradle Plugins and what they add to a Gradle build:

Gradle at its core intentionally provides little useful functionality for real world automation. All of the useful features, such as the ability to compile Java code for example, are added by plugins. Plugins add new tasks (e.g. JavaCompile), domain objects (e.g. SourceSet), conventions (e.g. main Java source is located at src/main/java) as well as extending core objects and objects from other plugins.

This post looks at some of the tasks, domain objects, and conventions that the Java Plugin brings to a Gradle build. To start, I need a very simple Gradle build file. It consists solely of a single line that applies the Java plugin. It is shown next in the Gradle build file build-java-plugin.gradle.

build-java-plugin.gradle
apply plugin: 'java'

With that single-line Gradle build file in place, it's easy to see which Gradle tasks the plugin-provides by running the command gradle -b build-java-plugin.gradle tasks. The next two screen snapshots show the output of running an empty Gradle build file followed by the output of running the Gradle build file with only the application of the Java plugin.

By comparing the output from running Gradle "tasks" against an empty build file to the output from running Gradle "tasks" against the build file with the Java plugin applied, we can see that the Gradle has the same set of "Build Setup tasks" and "Help tasks" whether the plugin is applied or not. More significantly, we see that the Java plugin adds many new tasks categorized as "Build tasks" (assemble, build, buildDependents, buildNeeded, classes, clean, jar, testClasses), "Documentation tasks" (javadoc), "Verification tasks" (check, test), and "Rules".

One feature I enjoy in Gradle 1.10 that Gradle 1.8 (the previous version I used) did not have is the ability on the command line to ask for details on a specific Gradle task. This is demonstrated in the next screen snapshot for Java Plugin tasks compileJava, jar, and javadoc. All three tasks have details written to standard output by using the help --task <task_name> command on the command line. These details on the Java Plugin tasks can also be found in the Gradle User Guide.

Because Gradle is built on Groovy, it's fairly easy to determine characteristics of the Java Plugin using "brute force." The next code listing, for build-java-plugin-properties.gradle, demonstrates using Groovy to determine the Gradle properties (those which can be specified with -P as opposed to system properties specified with -D) available to the build script before and after applying the Java plugin and then uses Groovy's highly convenient overridden subtraction operator to find the differences. The names and values of all of the properties added to the Gradle script by the Java Plugin (except the property "properties") are presented in alphabetical order.

// build-java-plugin-properties.gradle
//
// Displays properties that Gradle Java Plugin adds beyond properties already
// specified for any Gradle build.

def propertiesBefore = this.properties

apply plugin: 'java'

def propertiesAfter = this.properties

def extraProperties = propertiesAfter - propertiesBefore

def extraPropertiesKeys = new TreeSet<String>()
extraProperties.each
{ property ->
   if (property.key != "properties")
   {
      extraPropertiesKeys.add(property.key)
   }
}

extraPropertiesKeys.each
{ key ->
   println "${key} : ${extraProperties.get(key)}"
}

The next image shows a screen snapshot with the output from running this script. The screen snapshot does not show the full output, but a larger piece of the output (all the properties) is shown in text after the image.

Output from Running Above Gradle Script to See Java Plugin Properties

apiDocTitle : gradleExample API
archivesBaseName : gradleExample
assemble : task ':assemble'
binaries : [classes 'main', classes 'test']
build : task ':build'
buildDependents : task ':buildDependents'
buildNeeded : task ':buildNeeded'
buildTasks : [build]
check : task ':check'
classes : task ':classes'
clean : task ':clean'
compileJava : task ':compileJava'
compileTestJava : task ':compileTestJava'
defaultArtifacts : org.gradle.api.internal.plugins.DefaultArtifactPublicationSet_Decorated@bc80d8
dependencyCacheDir : C:\java\examples\groovyExamples\gradleExample\build\dependency-cache
dependencyCacheDirName : dependency-cache
distsDir : C:\java\examples\groovyExamples\gradleExample\build\distributions
distsDirName : distributions
docsDir : C:\java\examples\groovyExamples\gradleExample\build\docs
docsDirName : docs
inheritedScope : org.gradle.api.internal.ExtensibleDynamicObject$InheritedDynamicObject@c10304
jar : task ':jar'
javadoc : task ':javadoc'
libsDir : C:\java\examples\groovyExamples\gradleExample\build\libs
libsDirName : libs
manifest : org.gradle.api.java.archives.internal.DefaultManifest@1ad3677
metaInf : []
module : org.gradle.api.internal.artifacts.ProjectBackedModule@d2eead
processResources : task ':processResources'
processTestResources : task ':processTestResources'
rebuildTasks : [clean, build]
reporting : org.gradle.api.reporting.ReportingExtension_Decorated@33ab8f
reportsDir : C:\java\examples\groovyExamples\gradleExample\build\reports
reportsDirName : reports
runtimeClasspath : file collection
sourceCompatibility : 1.7
sourceSets : [source set 'main', source set 'test']
sources : [[source set 'main:java', source set 'main:resources'], [source set 'test:java', source set 'test:resources']]
status : integration
targetCompatibility : 1.7
test : task ':test'
testClasses : task ':testClasses'
testReportDir : C:\java\examples\groovyExamples\gradleExample\build\reports\tests
testReportDirName : tests
testResultsDir : C:\java\examples\groovyExamples\gradleExample\build\test-results
testResultsDirName : test-results

Gradle makes it easy to see all the Gradle properties using the command "gradle properties", but this command line action shows all properties regardless of their source (Gradle itself or a plugin).

Each Gradle task that the Java Plugin adds to the build has its own set of properties. These properties can be identified in the Gradle Build Language Reference. The Task Types section of that document has links to each task type. The linked-to pages on each task type have details on the properties supported by that task type. For example, the Task Type JavaCompile is listed on its page as having properties such as classpath, destinationDir, and source.

The following rather extensive script displays the settings for the properties of the compileJava, jar, and javadoc Gradle Java Plugin tasks. This script demonstrates how powerful it can be to apply Groovy to identifying Gradle build settings. The script could be shorter if more reflection was used, but calling the tasks' properties out explicitly does have advantages in terms of readability and as a reference for what properties are available on each task.

build-java-plugin-metadata.gradle
// build-java-plugin-metadata.gradle
//
// Displays the properties associated with the Gradle Java Plugin tasks
// of "compileJava", "jar", and "javadoc".

import groovy.transform.Field

apply plugin: 'java'

@Field int MAX_COLUMNS = 80
@Field String headerSeparator = "=".multiply(MAX_COLUMNS)

printCompileJavaProperties()
printJarProperties()
printJavadocProperties()

def printCompileJavaProperties()
{
   printHeader("compileJava Task")
   println "compileJava.classpath:\n${extractStringRepresentation(compileJava.classpath)}"
   println "compileJava.destinationDir:\n${extractStringRepresentation(compileJava.destinationDir)}"
   println "compileJava.source:\n${extractStringRepresentation(compileJava.source)}"
   println "compileJava.options:\n${extractStringRepresentation(compileJava.options)}"
   println "compileJava.includes:\n${extractStringRepresentation(compileJava.includes)}"
   println "compileJava.excludes:\n${extractStringRepresentation(compileJava.excludes)}"
   println "compileJava.sourceCompatibility:\n${extractStringRepresentation(compileJava.sourceCompatibility)}"
   println "compileJava.targetCompatibility:\n${extractStringRepresentation(compileJava.targetCompatibility)}"
}

def printJarProperties()
{
   printHeader("jar Task")
   println "jar.appendix:\n${extractStringRepresentation(jar.appendix)}"
   println "jar.archiveName:\n${extractStringRepresentation(jar.archiveName)}"
   println "jar.archivePath:\n${extractStringRepresentation(jar.archivePath)}"
   println "jar.baseName:\n${extractStringRepresentation(jar.baseName)}"
   println "jar.caseSensitive:\n${extractStringRepresentation(jar.caseSensitive)}"
   println "jar.classifier:\n${extractStringRepresentation(jar.classifier)}"
   println "jar.destinationDir:\n${extractStringRepresentation(jar.destinationDir)}"
   println "jar.dirMode:\n${extractStringRepresentation(jar.dirMode)}"
   println "jar.duplicatesStrategy:\n${extractStringRepresentation(jar.duplicatesStrategy)}"
   println "jar.entryCompression:\n${extractStringRepresentation(jar.entryCompression)}"
   println "jar.excludes:\n${extractStringRepresentation(jar.excludes)}"
   println "jar.extension:\n${extractStringRepresentation(jar.extension)}"
   println "jar.fileMode:\n${extractStringRepresentation(jar.fileMode)}"
   println "jar.includeEmptyDirs:\n${extractStringRepresentation(jar.includeEmptyDirs)}"
   println "jar.includes:\n${extractStringRepresentation(jar.includes)}"
   println "jar.manifest:\n${extractStringRepresentation(jar.manifest)}"
   println "jar.source:\n${extractStringRepresentation(jar.source)}"
   println "jar.version:\n${extractStringRepresentation(jar.version)}"
}

def printJavadocProperties()
{
   printHeader("javadoc Task")
   println "javadoc.classpath:\n${extractStringRepresentation(javadoc.classpath)}"
   println "javadoc.destinationDir:\n${extractStringRepresentation(javadoc.destinationDir)}"
   println "javadoc.excludes:\n${extractStringRepresentation(javadoc.excludes)}"
   println "javadoc.executable:\n${extractStringRepresentation(javadoc.executable)}"
   println "javadoc.failOnError:\n${extractStringRepresentation(javadoc.failOnError)}"
   println "javadoc.includes:\n${extractStringRepresentation(javadoc.includes)}"
   println "javadoc.maxMemory:\n${extractStringRepresentation(javadoc.maxMemory)}"
   println "javadoc.options:\n${extractStringRepresentation(javadoc.options)}"
   println "javadoc.source:\n${extractStringRepresentation(javadoc.source)}"
   println "javadoc.title:\n${extractStringRepresentation(javadoc.title)}"
}

def String extractStringRepresentation(Object object)
{
   String returnString
   if (object in String)
   {
      returnString = "\t${object}\n"
   }
   else if (object in File)
   {
      returnString = "\t${object.canonicalPath}\n"
   }
   else if (object in FileCollection)  // FileTree is a FileCollection
   {
      StringBuilder filesStr = new StringBuilder()
      def files = object.files
      files.each
      { file ->
         filesStr << "\t" << file.canonicalPath << "\n" 
      }
      returnString = filesStr.toString()
   }
   else if (object in CompileOptions)
   {
      StringBuilder compileOptionsStr = new StringBuilder()
      def compileProperties = object.properties
      compileProperties.each
      { compileProperty ->
         if (compileProperty.value in DebugOptions)
         {
            compileOptionsStr << "\t" << compileProperty.key << ": " << extractStringRepresentation(compileProperty.value) << "\n"
         }
         else if (compileProperty.value in DependOptions)
         {
            compileOptionsStr << "\t" << compileProperty.key << ": " << extractStringRepresentation(compileProperty.value) << "\n"
         }
         else if (compileProperty.value in ForkOptions)
         {
            compileOptionsStr << "\t" << compileProperty.key << ": " << extractStringRepresentation(compileProperty.value) << "\n"
         }
         else if (compileProperty.key != "class")
         {
            compileOptionsStr << "\t" << compileProperty.key << ": " << compileProperty.value << "\n"
         } 
      }
      returnString = compileOptionsStr.toString()
   }
   else if (object in DebugOptions)
   {
      returnString = "\t${object.debugLevel}"
   }
   else if (object in DependOptions)
   {
      returnString = "\t${object.classpath}"
   }
   else if (object in ForkOptions)
   {
      returnString = "\t${object.executable} executable with ${object.tempDir} temp directory" 
   }
   else if (object in Set || object in Boolean || object in Number || object in Enum)
   {
      returnString = "\t${object.toString()}\n"
   }
   else if (object in Manifest)
   {
      StringBuilder manifestStr = new StringBuilder()
      def manifestAttributes = object.getAttributes()
      manifestAttributes.each
      { manifestAttribute ->
         manifestStr << "\t" << manifestAttribute.key << ": " << manifestAttribute.value << "\n" 
      }
      returnString = manifestStr.toString()
   }
   else if (object in MinimalJavadocOptions)
   {
      returnString = extractJavadocOptionsAsString(object)
   }
   else if (object == null)
   {
      returnString = "\tnull\n"
   }
   else
   {
      returnString = "\t${object?.class} was unexpected type.\n"
   }
   return returnString
}

def String extractJavadocOptionsAsString(MinimalJavadocOptions javadocOptions)
{
   StringBuilder javadocOptionsStr = new StringBuilder()

   javadocOptionsStr << "\tjavadoc.bootClasspath:"
   def bootClasspathFiles = javadocOptions.bootClasspath
   bootClasspathFiles.each
   { bootClasspathFile ->
      javadocOptionsStr << "\t\t" << bootClasspathFile.canonicalName << "\n" 
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.classpath:"
   def classpathFiles = javadocOptions.classpath
   classpathFiles.each
   { classpathFile ->
      javadocOptionsStr << "\t\t" << classpathFile.canonicalName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.destinationDirectory: " << javadocOptions.destinationDirectory?.canonicalName << "\n"

   javadocOptionsStr << "\tjavadocOptions.doclet: " << javadocOptions.doclet << "\n"

   javadocOptionsStr << "\tjavadocOptions.docletpath:"
   def docletpath = javadocOptions.docletpath
   docletpath.each
   { docletEntry ->
      javadocOptionsStr << "\t\t" << docletEntry.canonicalName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.encoding: " << javadocOptions.encoding << "\n"

   javadocOptionsStr << "\tjavadocOptions.extDirs:"
   def extDirs = javadocOptions.extDirs
   extDirs.each
   { extDir ->
      javadocOptionsStr << "\t\t" << extDir.canonicalName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.header: " << javadocOptions.header << "\n"

   javadocOptionsStr << "\tjavadocOptions.JFlags:"
   def jflags = javadocOptions.JFlags
   jflags.each
   { jflag ->
      javadocOptionsStr << "\t\t" << jflag << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.locale: " << javadocOptions.locale << "\n"

   javadocOptionsStr << "\tjavadocOptions.memberLevel: " << javadocOptions.memberLevel << "\n"

   javadocOptionsStr << "\tjavadocOptions.optionFiles:"
   def optionFiles = javadocOptions.optionFiles
   optionFiles.each
   { optionFile ->
      javadocOptionsStr << "\t\t" << optionFile.canonicalName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.outputLevel: " << javadocOptions.outputLevel << "\n"

   javadocOptionsStr << "\tjavadocOptions.overview: " << javadocOptions.overview << "\n"

   javadocOptionsStr << "\tjavadocOptions.source: " << javadocOptions.source << "\n"

   javadocOptionsStr << "\tjavadocOptions.sourceNames:"
   def sourceNames = javadocOptions.sourceNames
   sourceNames.each
   { sourceName ->
      javadocOptionsStr << "\t\t" << sourceName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.windowTitle: " << javadocOptions.windowTitle << "\n"

   return javadocOptionsStr.toString()
}

def printHeader(String headerText)
{
   println headerSeparator
   println "= ${headerText.center(MAX_COLUMNS-4)} ="
   println headerSeparator
}

I used the Groovy @Field annotation in this build file to make the variable to which it was applied available to methods in the build file. The @Field annotation was not available until Groovy 1.8 and this reminded me of something else significant to point out about Gradle and Groovy here: Gradle uses its own prepackaged Groovy rather than any other version of Groovy that might be installed on one's machine. You can determine which version of Groovy that is with the gradle --version command. The next screen snapshot demonstrates that my version of Groovy (2.1.6) is different than the version of Groovy (1.8.6) used by my installation of Gradle (Gradle 1.10). Because Gradle 1.10 comes with Groovy 1.8.6, I had the @Field annotation at my disposal.

Because the output from the last script is so lengthy, I show it here as text rather than in an image.

Output of Running Gradle on build-java-plugin-metadata.gradle
================================================================================
=                               compileJava Task                               =
================================================================================
compileJava.classpath:

compileJava.destinationDir:
 C:\java\examples\groovyExamples\gradleExample\build\classes\main

compileJava.source:
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Main.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Main2.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Main3.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Main4.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Temperature.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\TemperatureScale.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\TemperatureUnit.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\TemperatureUnit2.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\TemperatureUnit3.java

compileJava.options:
 bootClasspath: null
 fork: false
 encoding: null
 deprecation: false
 warnings: true
 forkOptions:  null executable with null temp directory
 failOnError: true
 useDepend: false
 includeJavaRuntime: false
 useAnt: false
 compilerArgs: []
 debug: true
 extensionDirs: null
 compiler: null
 debugOptions:  null
 verbose: false
 optimize: false
 dependOptions:  
 listFiles: false

compileJava.includes:
 []

compileJava.excludes:
 []

compileJava.sourceCompatibility:
 1.7

compileJava.targetCompatibility:
 1.7

================================================================================
=                                   jar Task                                   =
================================================================================
jar.appendix:
 null

jar.archiveName:
 gradleExample.jar

jar.archivePath:
 C:\java\examples\groovyExamples\gradleExample\build\libs\gradleExample.jar

jar.baseName:
 gradleExample

jar.caseSensitive:
 true

jar.classifier:
 

jar.destinationDir:
 C:\java\examples\groovyExamples\gradleExample\build\libs

jar.dirMode:
 null

jar.duplicatesStrategy:
 INCLUDE

jar.entryCompression:
 DEFLATED

jar.excludes:
 []

jar.extension:
 jar

jar.fileMode:
 null

jar.includeEmptyDirs:
 true

jar.includes:
 []

jar.manifest:
 Manifest-Version: 1.0

jar.source:
 C:\java\examples\groovyExamples\gradleExample\build\tmp\jar\MANIFEST.MF

jar.version:
 null

================================================================================
=                                 javadoc Task                                 =
================================================================================
javadoc.classpath:
 C:\java\examples\groovyExamples\gradleExample\build\classes\main
 C:\java\examples\groovyExamples\gradleExample\build\resources\main

javadoc.destinationDir:
 C:\java\examples\groovyExamples\gradleExample\build\docs\javadoc

javadoc.excludes:
 []

javadoc.executable:
 null

javadoc.failOnError:
 true

javadoc.includes:
 []

javadoc.maxMemory:
 null

javadoc.options:
 javadoc.bootClasspath:
 javadocOptions.classpath:
 javadocOptions.destinationDirectory: null
 javadocOptions.doclet: null
 javadocOptions.docletpath:
 javadocOptions.encoding: null
 javadocOptions.extDirs:
 javadocOptions.header: null
 javadocOptions.JFlags:
 javadocOptions.locale: null
 javadocOptions.memberLevel: null
 javadocOptions.optionFiles:
 javadocOptions.outputLevel: QUIET
 javadocOptions.overview: null
 javadocOptions.source: null
 javadocOptions.sourceNames:
 javadocOptions.windowTitle: null

javadoc.source:
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Main.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Main2.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Main3.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Main4.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\Temperature.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\TemperatureScale.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\TemperatureUnit.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\TemperatureUnit2.java
 C:\java\examples\groovyExamples\gradleExample\src\main\java\dustin\examples\TemperatureUnit3.java

javadoc.title:
 gradleExample API

:help

Welcome to Gradle 1.10.

To run a build, run gradle  ...

To see a list of available tasks, run gradle tasks

To see a list of command-line options, run gradle --help

BUILD SUCCESSFUL

Total time: 14.041 secs

The example shown above works well for identifying specific properties associated with the Java Gradle plugin. This works fine, but its limitations include the need to write explicit code for each property whose value is desired. This implies further limitations of not necessarily knowing all the properties that are available (I used the documentation to explicitly print out values in the example above). A further implied limitation is that the script above will not display any properties values that are added to those tasks in the future. The next Gradle build example is based on the previous example, but this example does not explicitly state the tasks and properties to display. Instead, it finds all Tasks associated with the root project and then prints all properties associated with each of those Tasks.

build-java-plugin-metadata-reflection.gradle
// build-java-plugin-metadata-reflection.gradle
//
// Displays the properties associated with the tasks associated with the Gradle
// root project.
//

import groovy.transform.Field

apply plugin: 'java'

@Field int MAX_COLUMNS = 80
@Field String headerSeparator = "=".multiply(MAX_COLUMNS)

def rootProject = getRootProject()
def tasks = rootProject.tasks
tasks.each
{ task ->
   printTaskProperties(task)
}


def printTaskProperties(Task task)
{
   printHeader("Task " + task.name)
   def taskProperties = task.properties
   taskProperties.each
   { taskProperty ->
      println "${task.name}.${taskProperty.key}=${extractStringRepresentation(taskProperty.value)}"
   }
}

def String extractStringRepresentation(Object object)
{
   String returnString
   if (object in String)
   {
      returnString = "\t${object}\n"
   }
   else if (object in File)
   {
      returnString = "\t${object.canonicalPath}\n"
   }
   else if (object in FileCollection)  // FileTree is a FileCollection
   {
      StringBuilder filesStr = new StringBuilder()
      def files = object.files
      files.each
      { file ->
         filesStr << "\t" << file.canonicalPath << "\n" 
      }
      returnString = filesStr.toString()
   }
   else if (object in CompileOptions)
   {
      StringBuilder compileOptionsStr = new StringBuilder()
      def compileProperties = object.properties
      compileProperties.each
      { compileProperty ->
         if (compileProperty.value in DebugOptions)
         {
            compileOptionsStr << "\t" << compileProperty.key << ": " << extractStringRepresentation(compileProperty.value) << "\n"
         }
         else if (compileProperty.value in DependOptions)
         {
            compileOptionsStr << "\t" << compileProperty.key << ": " << extractStringRepresentation(compileProperty.value) << "\n"
         }
         else if (compileProperty.value in ForkOptions)
         {
            compileOptionsStr << "\t" << compileProperty.key << ": " << extractStringRepresentation(compileProperty.value) << "\n"
         }
         else if (compileProperty.key != "class")
         {
            compileOptionsStr << "\t" << compileProperty.key << ": " << compileProperty.value << "\n"
         } 
      }
      returnString = compileOptionsStr.toString()
   }
   else if (object in DebugOptions)
   {
      returnString = "\t${object.debugLevel}"
   }
   else if (object in DependOptions)
   {
      returnString = "\t${object.classpath}"
   }
   else if (object in ForkOptions)
   {
      returnString = "\t${object.executable} executable with ${object.tempDir} temp directory" 
   }
   else if (object in Set || object in List || object in Boolean || object in Number || object in Enum || object in Class)
   {
      returnString = "\t${object.toString()}\n"
   }
   else if (object in Manifest)
   {
      StringBuilder manifestStr = new StringBuilder()
      def manifestAttributes = object.getAttributes()
      manifestAttributes.each
      { manifestAttribute ->
         manifestStr << "\t" << manifestAttribute.key << ": " << manifestAttribute.value << "\n" 
      }
      returnString = manifestStr.toString()
   }
   else if (object in MinimalJavadocOptions)
   {
      returnString = extractJavadocOptionsAsString(object)
   }
   else if (object in Convention)
   {
      StringBuilder conventionStr = new StringBuilder()
      object.plugins.each?.keyset
      { plugin ->
         conventionStr << "\t" << plugin << "\n"
      }
      returnString = conventionStr.toString()
   }
   else if (object in LoggingManager)
   {
      returnString = "\n\tCurrent Log Level: ${object.level}\n\tStandard Error: ${object.standardErrorCaptureLevel}\n\tStandard Output: ${object.standardOutputCaptureLevel}\n"
   }
   else if (object == null)
   {
      returnString = "\tnull\n"
   }
   else
   {
      returnString = "\t${object?.class} was unexpected type with value of ${object}.\n"
   }
   return returnString
}

def String extractJavadocOptionsAsString(MinimalJavadocOptions javadocOptions)
{
   StringBuilder javadocOptionsStr = new StringBuilder()

   javadocOptionsStr << "\tjavadoc.bootClasspath:"
   def bootClasspathFiles = javadocOptions.bootClasspath
   bootClasspathFiles.each
   { bootClasspathFile ->
      javadocOptionsStr << "\t\t" << bootClasspathFile.canonicalName << "\n" 
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.classpath:"
   def classpathFiles = javadocOptions.classpath
   classpathFiles.each
   { classpathFile ->
      javadocOptionsStr << "\t\t" << classpathFile.canonicalName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.destinationDirectory: " << javadocOptions.destinationDirectory?.canonicalName << "\n"

   javadocOptionsStr << "\tjavadocOptions.doclet: " << javadocOptions.doclet << "\n"

   javadocOptionsStr << "\tjavadocOptions.docletpath:"
   def docletpath = javadocOptions.docletpath
   docletpath.each
   { docletEntry ->
      javadocOptionsStr << "\t\t" << docletEntry.canonicalName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.encoding: " << javadocOptions.encoding << "\n"

   javadocOptionsStr << "\tjavadocOptions.extDirs:"
   def extDirs = javadocOptions.extDirs
   extDirs.each
   { extDir ->
      javadocOptionsStr << "\t\t" << extDir.canonicalName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.header: " << javadocOptions.header << "\n"

   javadocOptionsStr << "\tjavadocOptions.JFlags:"
   def jflags = javadocOptions.JFlags
   jflags.each
   { jflag ->
      javadocOptionsStr << "\t\t" << jflag << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.locale: " << javadocOptions.locale << "\n"

   javadocOptionsStr << "\tjavadocOptions.memberLevel: " << javadocOptions.memberLevel << "\n"

   javadocOptionsStr << "\tjavadocOptions.optionFiles:"
   def optionFiles = javadocOptions.optionFiles
   optionFiles.each
   { optionFile ->
      javadocOptionsStr << "\t\t" << optionFile.canonicalName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.outputLevel: " << javadocOptions.outputLevel << "\n"

   javadocOptionsStr << "\tjavadocOptions.overview: " << javadocOptions.overview << "\n"

   javadocOptionsStr << "\tjavadocOptions.source: " << javadocOptions.source << "\n"

   javadocOptionsStr << "\tjavadocOptions.sourceNames:"
   def sourceNames = javadocOptions.sourceNames
   sourceNames.each
   { sourceName ->
      javadocOptionsStr << "\t\t" << sourceName << "\n"
   }
   javadocOptionsStr << "\n"

   javadocOptionsStr << "\tjavadocOptions.windowTitle: " << javadocOptions.windowTitle << "\n"

   return javadocOptionsStr.toString()
}

def printHeader(String headerText)
{
   println headerSeparator
   println "= ${headerText.center(MAX_COLUMNS-4)} ="
   println headerSeparator
}

Because this output is for all properties associated with all Tasks associated with the Gradle build's root project, the output is too lengthy to include here. Not all of the property value instances have classes that the extractStringRepresentation(Object object) method is prepared to handle, but those cases could be added to the if-else if structure of that method to handle them. This version of the Gradle build is more generic than the earlier one and prints out properties associated with Tasks that are grouped by Task.

Because a Gradle build is tightly coupled to Groovy, Groovy syntax and features can be used to learn more about the Gradle build. The examples in this post took advantage of numerous Groovy niceties. The reason that the Gradle build code above is so verbose is because most of the Gradle classes used for property values do NOT have overridden toString() methods and so no really useful output is shown without special code to call specific methods to get useful representations. I didn't do it in this post's examples, but another option to deal with lack of overridden toString() methods would be to use Groovy's interception capabilities (metaClass.invokeMethod) to intercept calls to toString() and provide an overridden version. That would be essentially the same code as used above, but would be encapsulated in the intercepting objects rather than contained in the script code.

Conclusion

Gradle has really nice documentation (especially the Gradle User Guide and the Gradle Build Language Reference) and most of the tasks and properties associated with the Java Plugin for Gradle (and other plugins) are easily accessible from that documentation. However, I like to know how to programmatically identify important conventions in case the documentation is ever mistaken or I use a version different than the documentation supports. Another objective of this post has been to demonstrate how useful it can be to know Groovy when working with Gradle. It is for this reason that I believe that the rising prominence of Gradle cannot help but increase interest in Groovy.

2 comments:

Mike Miller said...

Excellent post - it always seem like 'convention over configuration' meant that "we don't have to document it - it's convention", so it's great to be able to figure it out or find it documented somewhere!

@DustinMarx said...

Mike,

Thanks for the comment. I definitely have felt the way you describe with more than one product built on the concept of convention over configuration.

Dustin