Please explain the Android build.gradle groovy syn

Question

What does the following groovy syntax really mean?

The Gradle docs tout how the build.gradle is just groovy. The Android team has simplified the default build.gradle to the point that it doesn't look like code (to me at least). Please explain what this is doing in terms of groovy syntax. For example, are these global variable declarations that the Android plugin uses?

Bonus points if you include references to http://groovy-lang.org/syntax.html as part of your explanation.

apply plugin: 'com.android.application'

android {
    compileSdkVersion 21
    buildToolsVersion "21.1.2"

    defaultConfig {
        applicationId "com.crittercism"
        minSdkVersion 15
        targetSdkVersion 21
        versionCode 5
        versionName "5.0"
    }

}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
}

Answer 1

Thanks to AndroidGuy for supplying the excellent video that informed me of the information below. The video is 35 minutes long, so here's the TL;DR.

Most of this syntax is a mixture of method calls and closures. The closures are represented by curly braces. Also note that method calls do not require parenthesis.

apply plugin: 'com.android.application'

This is calling the apply method on the project object with a single named parameter "plugin". The project object is the top level object supplied by Gradle.

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
}

This is setting the dependencies property of the project object. Groovy properties are basically shorthand for getters and setters. The dependencies property is a Closure object that delegates to DependencyHandler. Groovy delegation is essentially a way to augment the scope resolution of a closure. The dependencies closure contains a single method call to compile, which takes a FileTree positional parameter. The FileTree is generated by the fileTree method which is defined in the project object. The compile method is still a bit nebulous to me. It appears to come from the Java plugin, but it isn't explicitly documented there. The 'compile' part is still a bit magical to me.

android {
    ...
}

I'll leave the 'android' section as an exercise to the reader. The Android Gradle Domain Specific Language (DSL) is not available on the web. You have to download it.

Answer 2

You can think of a gradle build script as some code which is delegated to an object which can respond to method calls written in it.

The script uses a lot of Groovy syntactic sugar, so removing them, it should look like this:

apply( [plugin: 'com.android.application'] );

android({
    compileSdkVersion( 21 );
    buildToolsVersion( "21.1.2" );

    defaultConfig({
        applicationId( "com.crittercism" );
        minSdkVersion( 15 );
        targetSdkVersion( 21 );
        versionCode( 5 );
        versionName( "5.0" );
    });
});

dependencies({
    compile( fileTree([dir: 'libs', include: ['*.jar']]) );
});

So the script is really a bunch of method calls:

• def apply(Map)
• def android(Closure)
• def dependencies(Closure)

This android(Closure) will receive a closure and will delegate the methods called in it to an object which can respond to these methods:

• def compileSdkVersion(Integer)
• def buildToolsVersion(String)
• ...

Given that, we can parse the script, delegate it to some object and then execute it.

Delegating using DelegatingBaseScript is one way to do it (not sure if Gradle does it this way). Here is a dumbed down working version:

import org.codehaus.groovy.control.CompilerConfiguration

gradleScript = '''
apply plugin: 'com.android.application'

android({
    compileSdkVersion( 21 )
    buildToolsVersion( "21.1.2" )
})'''


class PocketGradle {
  def config = [apply:[]].withDefault { [:] }

  def apply(map) {
    config.apply << map.plugin
  }

  def android(Closure closure) {
    closure.delegate = new Expando(
        compileSdkVersion: { Integer version -> 
          config.android.compileSdkVersion = version 
        },
        buildToolsVersion : { String version ->
          config.android.buildToolsVersion = version
        },
    )
    closure()
  }
}

def compiler = new CompilerConfiguration(scriptBaseClass: DelegatingScript.class.name)

shell = new GroovyShell(this.class.classLoader, new Binding(), compiler)

script = shell.parse gradleScript
script.setDelegate( gradle = new PocketGradle() )
script.run()

assert gradle.config == [
  apply: ['com.android.application'],
  android: [
    compileSdkVersion: 21,
    buildToolsVersion: '21.1.2'
  ]
]

You can execute the script in Groovy Web Console (click "Edit in console" and then "Execute script").

Most of the syntax explanation are in the DSL section:

1. Command chains

Groovy lets you omit parentheses around the arguments of a method call for top-level statements. "command chain" feature extends this by allowing us to chain such parentheses-free method calls, requiring neither parentheses around arguments, nor dots between the chained calls.

There is also Groovy ConfigSlurper, but i'm not sure if it can go as far as Gradle wants to.

Answer 3

I know I shouldn't just post a link as an answer, but there's really no better explanation than this:

"An introduction to Groovy, Gradle and the Android plugin" by Daniel Lew