A case study of the usage of Gradle in the Ratpack web framework. First, we'll examine the Ratpack Gradle plugins, including their functionality, implementation, and testing. Next, we'll examine the build script for the Ratpack project itself. Here, we'll discuss various details of the project's build, including handling multiple projects, multiple types of testing, support for multiple styles of target hardware (developer workstations, cloud CI), and more. For each, we'll go over the desired behavior, how it was achieved, and why it was necessary.

1. The Gradle in
Ratpack: Dissected
Presented by David Carr
Gradle Summit 2016 - June 22
GitHub: davidmc24
Twitter: @varzof

2. Who Am I?
• Systems Architect at
CommerceHub
• Java/Groovy Developer
• Gradle Enthusiast
• Ratpack Contributor

3. What is Ratpack?
• A web framework
• A set of Java libraries
• Purely a runtime
• No installable package
• No coupled/required build tooling
• Gradle recommended; plugins provided

4. Ratpack Hello World
Using the ratpack-groovy Gradle plugin

5. build.gradle
plugins {
id "io.ratpack.ratpack-groovy"
version "1.3.3"
}
repositories {
jcenter()
}
dependencies {
runtime "org.slf4j:slf4j-simple:1.7.21"
}

6. src/ratpack/ratpack.groovy
import static
ratpack.groovy.Groovy.ratpack
ratpack {
handlers {
get {
render "Hello world!n"
}
}
}

7. gradle run
$ gradle run
:compileJava UP-TO-DATE
:compileGroovy UP-TO-DATE
:processResources UP-TO-DATE
:classes UP-TO-DATE
:configureRun
:run
[main] INFO ratpack.server.RatpackServer -
Starting server...
[main] INFO ratpack.server.RatpackServer -
Building registry...
[main] INFO ratpack.server.RatpackServer -
Ratpack started (development) for
http://localhost:5050

8. gradle run --continuous
$ gradle run --continuous --quiet
[main] INFO ratpack.server.RatpackServer - Starting server...
[main] INFO ratpack.server.RatpackServer - Building
registry...
[main] INFO ratpack.server.RatpackServer - Ratpack started
(development) for http://localhost:5050
[main] INFO ratpack.server.RatpackServer - Stopping server...
[main] INFO ratpack.server.RatpackServer - Server stopped.
[main] INFO ratpack.server.RatpackServer - Starting server...
[main] INFO ratpack.server.RatpackServer - Building
registry...
[main] INFO ratpack.server.RatpackServer - Ratpack started
(development) for http://localhost:5050
$

9. Ratpack Gradle Plugins
Base, Java, Groovy

10. RatpackBasePlugin
class RatpackBasePlugin
implements Plugin<Project> {
@Override
void apply(Project project) {
project.extensions.create(
"ratpack", RatpackExtension,
project)
}
}

11. RatpackPlugin
private static final GradleVersion
GRADLE_VERSION_BASELINE =
GradleVersion.version("2.6")
…
void apply(Project project) {
def gradleVersion = GradleVersion.version(
project.gradle.gradleVersion)
if (gradleVersion < GRADLE_VERSION_BASELINE) {
throw new GradleException(
"Ratpack requires Gradle version
${GRADLE_VERSION_BASELINE.version}
or later")
}

12. RatpackPlugin
project.plugins.apply(ApplicationPlugin)
project.plugins.apply(RatpackBasePlugin)
RatpackExtension ratpackExtension =
project.extensions.findByType(
RatpackExtension)
SourceSetContainer sourceSets =
project.sourceSets
def mainSourceSet =
sourceSets[SourceSet.MAIN_SOURCE_SET_NAME]
mainSourceSet.resources.srcDir {
ratpackExtension.baseDir }

13. RatpackPlugin
project.dependencies {
compile ratpackExtension.core
testCompile ratpackExtension.test
}

14. RatpackExtension
class RatpackExtension {
…
private final
DependencyHandler dependencies
File baseDir
RatpackExtension(Project project) {
this.dependencies =
project.dependencies
baseDir = project.file('src/ratpack')
}

15. RatpackExtension
class RatpackExtension {
public static final String GROUP = "io.ratpack"
private final version =
getClass().classLoader.getResource(
"ratpack/ratpack-version.txt").text.trim()
…
Dependency getGroovyTest() {
dependency("groovy-test")
}
Dependency dependency(String name) {
dependencies.create(
"${GROUP}:ratpack-${name}:${version}")
}
}

16. RatpackPlugin
JavaExec runTask =
project.tasks.findByName("run") as JavaExec
def configureRun =
project.task("configureRun")
configureRun.doFirst {
runTask.with {
systemProperty "ratpack.development", true
}
}
runTask.dependsOn configureRun

17. RatpackGroovyPlugin
class RatpackGroovyPlugin
implements Plugin<Project> {
@Override
void apply(Project project) {
project.plugins.apply(RatpackPlugin)
project.plugins.apply(GroovyPlugin)
project.mainClassName =
"ratpack.groovy.GroovyRatpackMain"
…

18. RatpackGroovyPlugin
…
def ratpackExtension =
project.extensions
.getByType(RatpackExtension)
project.dependencies {
compile ratpackExtension.groovy
testCompile
ratpackExtension.groovyTest
}
}
}

19. Plugin Testing
Using Spock and Gradle TestKit

20. DslSpec
class DslSpec extends FunctionalSpec {
def "can use extension to add dependencies"() {
given:
buildFile << """
configurations.all {
transitive = false // we don't need jackson itself for this test
}
dependencies {
compile ratpack.dependency("jackson-guice")
}
task showDeps {
doLast {
file("deps.txt") << configurations.compile.dependencies*.toString().join('n')
}
}
"""
when:
run "showDeps"
then:
file("deps.txt").text.contains("ratpack-jackson-guice")
}
}

21. InstallDistSpec
def "everything goes in the right place"() {
given:
file("src/ratpack/ratpack.groovy") << """
import static ratpack.groovy.Groovy.*
import ratpack.server.Stopper
ratpack {
serverConfig { port 0 }
handlers {
get {
onClose { get(Stopper).stop() }
render "foo"
}
get("stop") {
onClose { get(ratpack.server.Stopper).stop() }
}
}
}
"""

22. InstallDistSpec
when:
run "installDist"
def process = new ProcessBuilder()
.directory(file("build/install/test-app"))
.command(osSpecificCommand())
.start()
def port = scrapePort(process)
then:
new PollingConditions().within(10) {
try {
urlText(port) == "foo"
} catch (ConnectException ignore) {
false
}
}
cleanup:
if (port) {
url(port, "stop")
}
process?.destroy()
process?.waitFor()
}

23. FunctionalSpec
abstract class FunctionalSpec extends Specification {
GradleRunner runner(String... args) {
GradleRunner.create()
.withProjectDir(dir.root)
.withDebug(true)
.forwardOutput()
.withTestKitDir(getTestKitDir())
.withArguments(args.toList())
}
BuildResult run(String... args) {
runner(args).build()
}
BuildResult fail(String... args) {
runner(args).buildAndFail()
}

24. FunctionalSpec
File getBuildFile() {
makeFile("build.gradle")
}
File makeFile(String path) {
def f = file(path)
if (!f.exists()) {
def parts = path.split("/")
if (parts.size() > 1) {
dir.newFolder(*parts[0..-2])
}
dir.newFile(path)
}
f
}
File file(String path) {
def file = new File(dir.root, path)
assert file.parentFile.mkdirs() || file.parentFile.exists()
file
}

25. FunctionalSpec
def setup() {
file("settings.gradle") << "rootProject.name = 'test-app'"
buildFile << """
buildscript {
repositories {
maven { url "${localRepo.toURI()}" }
jcenter()
}
repositories { jcenter() }
dependencies {
classpath 'com.github.jengelman.gradle.plugins:shadow:1.2.3'
classpath 'io.ratpack:ratpack-gradle:${RATPACK_VERSION}'
}
}
apply plugin: 'io.ratpack.ratpack-groovy'
apply plugin: 'com.github.johnrengelman.shadow'
version = "1.0"
repositories {
maven { url "${localRepo.toURI()}" }
jcenter()
}
dependencies { compile 'org.slf4j:slf4j-simple:1.7.12' }
"""
file("src/ratpack/ratpack.properties") << "port=0n"
}

26. FunctionalSpec
int scrapePort(Process process) {
int port = -1
def latch = new CountDownLatch(1)
Thread.start {
process.errorStream.eachLine { String line ->
System.err.println(line)
if (latch.count) {
if (line.contains("Ratpack started for http://localhost:")) {
def matcher = (line =~ "http://localhost:(d+)")
port = matcher[0][1].toString().toInteger()
latch.countDown()
}
}
}
}
if (!latch.await(15, TimeUnit.SECONDS)) {
throw new RuntimeException("Timeout waiting for application to start")
}
port
}

27. Ratpack Project Build

28. Build File Naming
def setBuildFile(project) {
project.buildFileName =
"${project.name}.gradle"
project.children.each {
setBuildFile(it)
}
}
setBuildFile(rootProject)

29. Build Logic Re-use
Usage:
apply from:
"$rootDir/gradle/javaModule.gradle"
Extracted build files:
checkstyle, codenarc, dependencies,
dependencyRules, groovyModule, javaModule,
markdown2book, pom, projectLocalRepo, publish,
ratpackLocal, versionFile

30. Version as a Resource
task writeVersionNumberFile {
def versionFile = file("src/main/resources/ratpack/ratpack-version.txt")
inputs.property "version", project.version
outputs.file versionFile
doFirst {
assert versionFile.parentFile.mkdirs()
|| versionFile.parentFile.directory
versionFile.text = project.version
}
}
processResources.dependsOn writeVersionNumberFile
plugins.withType(EclipsePlugin) {
eclipseProject.dependsOn writeVersionNumberFile
}
plugins.withType(IdeaPlugin) {
ideaModule.dependsOn writeVersionNumberFile
}

31. Minimum Groovy
Version
processResources {
inputs.property("groovyVersion",
commonVersions.groovy)
def minimumGroovyVersionFile =
file("src/main/resources/ratpack/
minimum-groovy-version.txt")
outputs.file minimumGroovyVersionFile
doFirst {
minimumGroovyVersionFile.parentFile.mkdirs()
minimumGroovyVersionFile.text =
commonVersions.groovy
}
}

32. Java Settings
def jvmEncoding =
java.nio.charset.Charset.defaultCharset().name()
if (jvmEncoding != "UTF-8") {
throw new IllegalStateException(
"Build environment must be UTF-8 (it is:
$jvmEncoding) - add '-Dfile.encoding=UTF-8'
to the GRADLE_OPTS environment variable ")
}
if (!JavaVersion.current().java8Compatible) {
throw new IllegalStateException(
"Must be built with Java 8 or higher")
}

33. Download Dependencies
task downloadDependencies << {
allprojects { p ->
configurations.each { c ->
println "Downloading dependencies
for $p.path - $c.name"
c.files
}
}
}

34. Version Management
ext {
commonVersions = [
netty: "4.1.1.Final",
slf4j: "1.7.12",
spock: "1.0-groovy-2.4",
]
commonDependencies = [
slf4j: "org.slf4j:slf4j-api:${commonVersions.slf4j}",
spock: dependencies.create(
"org.spockframework:spock-core:${commonVersions.spock}", {
exclude group: "org.codehaus.groovy", module: "groovy-all"
}),
]
…
compile commonDependencies.slf4j
compile "io.netty:netty-codec-http:$commonVersions.netty"
compile "io.netty:netty-handler:$commonVersions.netty"

35. Alternate Groovy
Version
if (System.getenv('CI_GROOVY_VERSION')) {
commonVersions.groovy =
System.getenv('CI_GROOVY_VERSION')
if (commonVersions.groovy.endsWith('-SNAPSHOT')) {
allprojects {
repositories {
maven {
name 'JFrog OSS snapshot repo'
url 'https://oss.jfrog.org/oss-snapshot-local/'
}
}
}
}
}

36. Cloud CI Detection
ext {
isTravis = System.getenv("TRAVIS") != null
isDrone = System.getenv("DRONE") != null
isCodeship =
System.getenv("CI_NAME") == "codeship"
isSnapCi = System.getenv("SNAP_CI") != null
isAppveyor = System.getenv("APPVEYOR") != null
isHeroku = System.getenv("HEROKU") != null
isCloudCi = isTravis || isDrone || isCodeship
|| isSnapCi || isAppveyor
isCi = isCloudCi
}

37. Memory Usage
test {
maxParallelForks = 3
}
tasks.withType(GroovyCompile) {
groovyOptions.forkOptions.memoryMaximumSize = "512m"
}
tasks.withType(Test) {
jvmArgs "-Xss320k"
minHeapSize "120m"
maxHeapSize "280m"
doFirst {
if (isCloudCi) {
maxParallelForks 1
systemProperty "cloudCi", "true"
}
}
}

38. Command-line Options
In Snap CI:
GRADLE_OPTS=
-Xmx386m
-Xms386m
-Dorg.gradle.parallel.intra=true
./gradlew check
--parallel
--max-workers=2
--gradle-user-home ${SNAP_CACHE_DIR}/.gradle

39. Questions?
P.S. We're Hiring!
David M. Carr
Systems Architect
GitHub: davidmc24
Twitter: @varzof