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.3, “Gradle properties and system properties”).
Example 10.1. Skipping tasks using default property name
build.gradle
task autoskip << { println 'This should not be printed if the skip.autoskip system property is set.' }
Output of gradle -Dskip.autoskip autoskip
> 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.
Example 10.2. Skipping tasks using custom property
build.gradle
task skipMe << { println 'This should not be printed if the mySkipProperty system property is set to true.' } skipMe.skipProperties << 'mySkipProperty'
Output of gradle -DmySkipProperty skipMe
> 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 [6] except false (case does not matter), the actions of the task don't get executed.
By default tasks that depends on skipped task get executed. If you want to skip them, you have to declare this explicitly via the skip properties.
Example 10.3. Skipping depending tasks
build.gradle
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'
Output of gradle -Dskip.autoskip depends
> gradle -Dskip.autoskip depends :autoskip SKIPPED :depends SKIPPED BUILD SUCCESSFUL Total time: 1 secs
If the rules for skipping a task can't be expressed with a simple property, you can use the
StopExecutionException
. If this exception is thrown by an action,
the further execution of this action as well as the execution of
any following action of this task is skipped. The build continues with executing the next task.
Example 10.4. Skipping tasks with StopExecutionException
build.gradle
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' }
Output of gradle -q myTask
> gradle -q myTask I am not affected
This feature is helpful if you work with tasks provided by Gradle. It allows you to add conditional execution of the built-in actions of such a task.
You might be wondering why there is neither an import for the
StopExecutionException
nor do we access it via its fully qualified name. The reason is, that Gradle adds a set of default imports
to your script. These imports are customizable (see Appendix C, Existing IDE Support and how to cope without it).
Every task has also an enabled
flag which defaults to true
. Setting it to false
prevents the execution of any of the
task's actions.
Example 10.5. Enabling and disabling tasks
build.gradle
task disableMe << { println 'This should not be printed if the task is disabled.' } disableMe.enabled = false
Output of gradle disableMe
> gradle disableMe :disableMe SKIPPED BUILD SUCCESSFUL Total time: 1 secs
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):
Example 10.6. Directory creation with mkdir
build.gradle
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 }
Output of gradle -q compile
> gradle -q compile The class directory exists. I can operate
But Gradle offers you also Directory Tasks to deal with this.
Example 10.7. Directory creation with Directory tasks
build.gradle
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 }
Output of gradle -q otherResources
> gradle -q otherResources The class directory exists. I can operate
A Directory Task is a simple task whose name is a relative path to the project dir [7] . 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.
You can also directly add properties to your project objects using properties files. You can place a
gradle.properties
file in the Gradle user home directory (defaults to
) or in your project directory. For
multi-project builds you can place USER_HOME
/.gradlegradle.properties
files in any subproject directory.
The properties of the gradle.properties
can be accessed via the project object. The
properties file in 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 administration section (invisible to
normal users).
[8]
If the environment property follows the pattern
ORG_GRADLE_PROJECT_
,
propertyName
=somevaluepropertyName
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 pattern, which is
org.gradle.project.
.
propertyName
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.
Example 10.8. Setting properties with a gradle.properties file
gradle.properties
gradlePropertiesProp=gradlePropertiesValue systemPropertiesProp=shouldBeOverWrittenBySystemProp envPropertiesProp=shouldBeOverWrittenByEnvProp systemProp.system=systemValue
build.gradle
task printProps << { println commandLineProjectProp println gradlePropertiesProp println systemProjectProp println envProjectProp println System.properties['system'] }
Output of gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps
> gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps commandLineProjectPropValue gradlePropertiesValue systemPropertyValue envPropertyValue systemValue
You can access a project property in your build script simply by using its name as you would use a
variable. In case this property does not exists, an exception is thrown and the build fails. If your
build script relies on optional properties the user might set for example in a gradle.properties file,
you need to check for existence before you can access them. You can do this by using the method
hasProperty('propertyName')
which returns
true
or false
.
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.3, “Gradle properties and system properties”. Your gradle.properties file could look like
this:
Example 10.9. Accessing the web via a proxy
gradle.properties
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.
Example 10.10. Configuring arbitrary objects
build.gradle
task configure << { pos = configure(new java.text.FieldPosition(10)) { beginIndex = 1 endIndex = 5 } println pos.beginIndex println pos.endIndex }
Output of gradle -q configure
> gradle -q configure 1 5