Chapter 10. Tutorial - 'This and That'

Gradle offers multiple ways to skip the execution of a task.

You can set system property named skip.taskname or pass such property as a parameter to the gradle command using -D option (see Section 10.4, “Gradle Properties and System Properties”).

task autoskip << {
    println 'This should not be printed if the skip.autoskip system property is set.'
}

> gradle -Dskip.autoskip autoskip
:autoskip SKIPPED

BUILD SUCCESSFUL

Total time: 1 secs

You can also choose another another property that can be used to skip a task.

task skipMe << {
    println 'This should not be printed if the mySkipProperty system property is set to true.'
}
skipMe.skipProperties << 'mySkipProperty'

> gradle -DmySkipProperty skipMe
:skipMe SKIPPED

BUILD SUCCESSFUL

Total time: 1 secs

You can use this to add one or more skip properties to any task.

In both cases if the corresponding system property is set to any value ^[7] except false (case does not matter), the actions of the task don't get executed.

task autoskip << {
    println 'This should not be printed if the skip.autoskip system property is set.'
}
task depends(dependsOn: autoskip) << {
    println "This should not be printed if the skip.autoskip system property is set."
}
depends.skipProperties << 'skip.autoskip'

> gradle -Dskip.autoskip depends
:autoskip SKIPPED
:depends SKIPPED

BUILD SUCCESSFUL

Total time: 1 secs

task compile << {
    println 'We are doing the compile.'
}

compile.doFirst {
    // Here you would put arbitrary conditions in real life. But we use this as an integration test, so we want defined behavior.
    if (true) { throw new StopExecutionException() }
}
task myTask(dependsOn: 'compile') << {
   println 'I am not affected'
}

> gradle -q myTask
I am not affected

task disableMe << {
    println 'This should not be printed if the task is disabled.'
}
disableMe.enabled = false

> gradle disableMe
:disableMe SKIPPED

BUILD SUCCESSFUL

Total time: 1 secs

Gradle provides several ways you can find out many details of your build. This can be useful for understanding the structure and dependencies of your build, and for debugging problems. Firstly, Gradle provides several command-line options which show particular details of your build. And secondly, Gradle provides a project-reports plugin, which adds tasks to generate reports about your build.

Running gradle --tasks gives you a list of the tasks which make up the build, broken down by project. This report shows the default tasks, if any, of each project, and the description and dependencies of each task. Below is an example of this report:

> gradle -q --tasks
------------------------------------------------------------
Root Project
------------------------------------------------------------
Default Tasks: dists

:clean - Deletes the build directory (build)
:dists 
   -> :api:libs, :webapp:libs

------------------------------------------------------------
Project :api
------------------------------------------------------------
:api:libs 
rule - build<ConfigurationName>: builds the artifacts of the given configuration

------------------------------------------------------------
Project :webapp
------------------------------------------------------------
:webapp:libs 
rule - build<ConfigurationName>: builds the artifacts of the given configuration

Running gradle --dependencies gives you a list of the dependencies of the build, broken down by project. This report shows the configurations of each project. For each configuration, the direct and transitive dependencies of that configuration are shown. Below is an example of this report:

> gradle -q --dependencies
------------------------------------------------------------
Root Project
------------------------------------------------------------
No configurations

------------------------------------------------------------
Project :api
------------------------------------------------------------
compile
|-----api:unspecified:unspecified
      |-----commons-io:commons-io:1.2

------------------------------------------------------------
Project :webapp
------------------------------------------------------------
compile
|-----webapp:unspecified:unspecified
      |-----commons-io:commons-io:1.2

Running gradle --properties gives you a list of the properties of each project in the build.

Finally, you can use the project-reports plugin to add a number of reporting tasks to your project.

There is a common situation, that multiple tasks depend on the existence of a directory. Of course you can deal with this by adding a mkdir to the beginning of those tasks. But this is kind of bloated. There is a better solution (works only if the tasks that need the directory have a dependsOn relationship):

classesDir = new File('build/classes')
task resources << {
    classesDir.mkdirs()
    // do something
}
task compile(dependsOn: 'resources') << {
    if (classesDir.isDirectory()) {
        println 'The class directory exists. I can operate'
    }
    // do something
}

> gradle -q compile
The class directory exists. I can operate

But Gradle offers you also Directory Tasks to deal with this.

classes = dir('build/classes')
task resources(dependsOn: classes) << {
    // do something
}
task otherResources(dependsOn: classes) << {
    if (classes.dir.isDirectory()) {
        println 'The class directory exists. I can operate'
    }
    // do something
}

> gradle -q otherResources
The class directory exists. I can operate

A Directory Task is a simple task which name is a relative path to the project dir ^[8] . During the execution phase the directory corresponding to this path gets created if it does not exist yet. Another interesting thing to note in this example, is that you can also pass tasks objects to the dependsOn declaration of a task.

Gradle offers a variety of ways to add properties to your build. With the -D command line option you can pass a system property to the JVM which runs Gradle. The -D option of the gradle command has the same effect as the -D option of the java command.

There is also the possibility to directly add properties to your project objects. You can place a gradle.properties file either in the Gradle user home dir (defaults to USER_HOME/.gradle ) or in your project dir. For multiproject builds you can place gradle.properties files in any subproject. The properties of the gradle.properties can be accessed via the project object. The properties file in the the user's home directory has precedence over property files in the project directories.

You can also add properties directly to your project object via the -P command line option. For more exotic use cases you can even pass properties directly to the project object via system and environment properties. For example if you run a build on a continuous integration server where you have no admin rights for the machine. Your build script needs properties which values should not be seen by others. Therefore you can't use the -P option. In this case you can add an environment property in the project adminstration section (invisible to normal users). ^[9] If the environment property follows the pattern ORG_GRADLE_PROJECT_yourProperty=somevalue, yourProperty is added to your project object. If in the future CI servers support Gradle directly, they might start Gradle via its main method. Therefore we already support the same mechanism for system properties. The only difference is the prefix, which is org.gradle.project..

With the gradle.properties files you can also set system properties. If a property in such a file has the prefix systemProp. the property and its value are added to the system properties (without the prefix).

gradlePropertiesProp=gradlePropertiesValue
systemPropertiesProp=shouldBeOverWrittenBySystemProp
envPropertiesProp=shouldBeOverWrittenByEnvProp
systemProp.system=systemValue

task printProps << {
    println commandLineProjectProp
    println gradlePropertiesProp
    println systemProjectProp
    println envProjectProp
    println System.properties['system']
}

> gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps
commandLineProjectPropValue
gradlePropertiesValue
systemPropertyValue
envPropertyValue
systemValue

Setting a proxy for web access (for example for downloading dependencies) is easy. Gradle does not need to provide special functionality for this. The JVM can be instructed to go via proxy by setting certain system properties. You could set these system properties directly in your build script with System.properties['proxy.proxyUser'] = 'userid'. An arguably nicer way is shown in Section 10.4, “Gradle Properties and System Properties”. Your gradle.properties file could look like this:

systemProp.http.proxyHost=http://www.somehost.org
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=userid
systemProp.http.proxyPassword=password

We could not find a good overview for all possible proxy settings. The best we can offer are the constants in a file from the ant project. Here a link to the svn view. If anyone knows a better overview please let us know via the mailing list.

To improve the responsiveness Gradle caches the compiled build script by default. The first time you run a build for a project, Gradle creates a .gradle directory in which it puts the compiled build script. The next time you run this build, Gradle uses the compiled build script, if the timestamp of the compiled script is newer than the timestamp of the actual build script. Otherwise the build script gets compiled and the new version is stored in the cache. If you run Gradle with the -x option, any existing cache is ignored and the build script is compiled and executed on the fly. If you run Gradle with the -r option, the build script is always compiled and stored in the cache. That way you can always rebuild the cache if for example the timestamps for some reasons don't reflect that the build script needs to be recompiled.

You can configure arbitrary objects in the following very readable way.

task configure << {
    pos = configure(new java.text.FieldPosition(10)) {
        beginIndex = 1
        endIndex = 5
    }
    println pos.beginIndex
    println pos.endIndex
}

> gradle -q configure
1
5