[next] [prev] [prev-tail] [tail] [up]

Chapter 4
The ’This And That’ Tutorial

4.1 Skipping Tasks

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

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

  >gradle -q -bskipProperties.gradle -DmySkipProperty skipMe

The -D option of the gradle command has the same effect as the -D option of the java command. This way you can set system properties of the JVM that runs Gradle. You can add one ore more skip properties to any existing task. If the corresponding system property is set to any value/footnoteThe statement -Dprop sets the property to empty string, thus you don’t need to type more to skip a task. except false (case does not matter), the actions of the task don’t get executed. But often you don’t even need to set the skip properties. If you set a system property according to the pattern skip.taskname , the actions of this task don’t get executed.

  createTask('autoskip') {
      println 'This should not be printed if the skip.autoskip system property is set.'
  }

  >gradle -q -bautoskip.gradle -Dskip.autoskip autoskip

If you want tasks to be skipped, that depends on a skipped task, you have to declare this explicitly via the skip properties

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

  >gradle -q -bautoskipDepends.gradle -Dskip.autoskip depends

If the rules for skipping a task can’t be expressed with a simple property, you can use the StopExecutionException1 . 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.

  createTask('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() }
  }
  createTask('myTask', dependsOn: 'compile') {
     println 'I am not affected'
  }
  >gradle -q -bstopExecutionException.gradle 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 ??).

Every task has also a enabled flag which defaults to true. Setting it to false prevents the execution of any of the tasks actions.

  createTask('disableMe') {
              println 'This should not be printed if the task is disabled.'
          }.enabled = false
  >gradle -q -bdisableTask.gradle disableMe

4.2 Console Output

All available command line options are listed in Appendix C. You can also print them to your console with gradle -h. We want to look at the console output options in more detail.

Loglevel
Option Meaning
neither q nor d Gradle and Ant will print out info log messages.
q Only errors are printed to the console.
d Gradle and Ant will print out info and debug log messages.
Stacktraces
Option

Meaning

neither s nor f

No stacktraces are printed to the console in case of a build error (e.g. a compile error). Only in case of internal exceptions will stacktraces be printed. If the loglevel option d is choosen, truncated stacktraces are always printed.

s

Truncated stacktraces are printed. We recommend this over full stacktraces. Groovy full stacktraces are extremely verbose (Due to the underlying dynamic invocation mechanisms. Yet they usually do not contain relevant information for what has gone wrong in your code.)

f

The full stacktraces are printed out.

4.3 Directory Creation

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')
  createTask('resources') {
      classesDir.mkdirs()
      // do something
  }
  createTask('compile', dependsOn: 'resources') {
      if (classesDir.isDirectory()) {
          println 'The class directory exists. I can operate'
      }
      // do something
  }

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

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

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

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

A Directory Task is a simple task which name is a relative path to the project dir2 . 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.

4.4 Gradle Properties and System Properties

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.

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).3 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
  createTask('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

4.5 Accessing the web via a proxy

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 this system properties directly in your build script with System.properties[’proxy.proxyUser’] = ’userid’. An arguably nicer way is shown in section 4.4. 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.

[next] [prev] [prev-tail] [front] [up]