Should “apply plugin: ‘NAME’” be always on top of the page?
I have been using the Java and Eclipse plugin, and all the related tasks right after those. I always override the tasks “jar”, “dependencies”, “sourceSets”… Then, when I need to use the Maven plugin I start another block below with “apply plugin: ‘maven’” and the related tasks like “uploadArtifacts”. However, some configuration blocks (repositories, dependencies) are used by most of them… How should we better organize the script code? Group related tasks together? Given that the size of a build script can grow, what’s the best way to organize the blocks of related tasks?
How to add documentation? - I have used the property “description” inside of an existing task or in a property when defining a task. Since tasks are self-describing, I don’t see any need for adding comments or documentation. However, overridden tasks sometimes are not that descriptive… See below the as I had to override the task “compileAnnotatedModelJava” as it is one of the generated tasks for the named sourceSet “annotatedModel”.
sourceSets {
def tsunamiJavaDir = new File("$projectDir/…/tsunami/core/src/main/java").canonicalPath
annotatedModel {
java {
srcDir tsunamiJavaDir
include ‘**/domain/*’
}
} }
//Generates source-code using the Ctf Extention Annotation Processor in $tsunamiJavaDir // Note that this task is pre-defined for the sourceSets configuration “annotatedModel”. // http://gradle.org/current/docs/userguide/java_plugin.html#N1176B compileAnnotatedModelJava {
My thinking follows these lines: I put at the top the parts that will easily help the reader classify what kind of project it is. So, I put plugin declarations like groovy, java, war, etc at the top.
The next most likely thing I think the reader wants to know when they open a build script is what the dependencies of the project look like. That’s why I keep my repositories and dependency definitions very close to the top of the script. I group compile and testCompile dependencies separately, and within those I promote subproject dependencies to the top. I haven’t settled on a consistent style for where I place dependencies that I use for JavaExec or ant.taskdef.
The rest I consider to be the details and the reader can scroll down for those. I keep them following a logical flow from compile and processResources through to assembling artifacts.
After those come the details of artifact publishing and IDE configuration. These can grow to be big chunks of configuration, that IMO aren’t too interesting to the reader. In that case I pull them out into separate build scripts and include them using apply-from.
The very bottom of the script is where I place functions I’ve defined and version and task class implementations that are small enough to live in the build script.
I avoid documenting anything that someone familiar with Gradle would know. I only comment work-arounds or awkward fragments of configuration - anything that someone would miss the significance of in a dangerous way, or anything overly cryptic. A single-line comment normally suffices. Task descriptions I view as optional if the task name itself is explanatory. Task descriptions are a must for rules - however simple they may seem to the author.