What is the key to understanding the gradle API?

Old Forum
1

What is the key to understanding Gradle documentation? I must be missing something because I can’t understand or follow any of the Gradle docs or APIs.

I’m having to edit a previously written script at work. I see a variable named ‘ant’ and from a Google search I now know it is implicitly available in my gradle script and refers to an Object called AntBuilder. How am I supposed to know this from the gradle API? Where is the set of implicit objects defined?

Next… this ‘ant’ object has (I think?) a method called ‘java’ on it. Looking at the AntBuild API, none of these ‘ant-task’ methods are defined. How am I supposed to know what methods are available on the AntBuilder object?

Next… I need to know what parameters this ‘java’ method takes. Without API documentation, it is impossible to know. This appears to be the case for ALL Gradle documentation. If you don’t already happen to know what’s possible, there’s no way to figure it out.

What is the key to understanding an using Gradle. I’ve read the book and all documentation cover-to-cover and am none-the-wiser.

2

Have you studied the Ant chapter in the Gradle user guide and the Ant samples in the Gradle distribution? Are you aware of the Gradle DSL reference, the Javadoc and the Groovydoc?

AntBuilder comes from Groovy (see Using Ant from Groovy), though Gradle enriches it a bit. It’s mostly dynamic and doesn’t have that many methods on it (the ones it has are documented here). Its main purpose is to let you configure and execute Ant tasks in the same way as you would in an Ant build.xml, just with a groovyfied syntax for the XML (< becomes ‘{’ etc.).

AntBuilder has no ‘java’ method. You are probably trying to configure Ant’s ‘java’ task here. (By the way, you might want to use Gradle’s ‘JavaExec’ task instead.) Which properties are available for that task can be found in the Ant documentation. After all, AntBuilder is really just a gateway into Ant. Therefore, it cannot possibly have a fixed set of properties and methods.

1 Like
3

Incidentally, here’s the AntBuilder API URL I found that doesn’t list the ant-task methods:

http://gradle.org/docs/current/javadoc/index.html?org/gradle/api/AntBuilder.html

4

AntBuilder is a groovy builder, which intercepts undefinded methods and turns them into XML.

To take an example from the Ant manual:

<java classname="test.Main">
        <arg value="-h"/>
        <classpath>
            <pathelement location="dist/test.jar"/>
            <pathelement path="${java.class.path}"/>
        </classpath>
    </java>

Can be expressed as:

ant {
        java(classname: 'test.Main') {
            arg(value: '-h')
            classpath {
                pathelement(location: 'dist/test.jar')
                pathelement(path: "${properties['java.class.path']}")
            }
                      }
      }

In short, unknown methods become xml elements, named method arguments become attributes and closure blocks become the bodies of elements.

The beauty of it is that you can intersperse this with actual code. For example:

pathelement(path: configurations.strutschecker.asPath + ':' + configurations.compile.asPath)

Or, just to show how to dynamically add elements to the XML:

configurations.compile.asPath.split(/:/).grep{ it.startsWith('com.mycompany') }.each {
         pathelement(path: it)
    }

Where ‘it’ is an implicit argument to the closures containing it.

Hope this helps.

1 Like