This manual is a work in progress and is currently incomplete.
If you'd like to help improve it, and we hope you do, please see the README.

23 Building with Gradle

The recommended way to build Ratpack applications is to use the Gradle Build System, by way of the Gradle plugins provided by the Ratpack project.

Ratpack is purely a runtime toolkit and not also a development time tool like Ruby on Rails and Grails. This means that you can use whatever you like to build a Ratpack app. The provided Gradle plugins merely provide convenience and are not fundamental to Ratpack development.

1.23 Setup

The first requirement is to apply the Gradle plugin to your Gradle project…

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "io.ratpack:ratpack-gradle:2.0.0-rc-1"
  }
}

apply plugin: "io.ratpack.ratpack-java"

repositories {
  mavenCentral()
}

Or for a Groovy based Ratpack project…

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "io.ratpack:ratpack-gradle:2.0.0-rc-1"
  }
}

apply plugin: "io.ratpack.ratpack-groovy"

repositories {
  mavenCentral()
}

The 'io.ratpack.ratpack-java' plugin applies the core Gradle 'java' plugin. The 'io.ratpack.ratpack-groovy' plugin applies the core Gradle 'groovy' plugin. This means that you can start adding code and dependencies to your app like a standard Gradle based project (e.g. putting source in src/main/[groovy|java]). Note that the 'io.ratpack.ratpack-groovy' plugin implicitly applies the 'io.ratpack.ratpack-java' plugin.

2.23 Ratpack dependencies

To depend on a Ratpack extension library, simply add it as a regular implementation dependency…

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "io.ratpack:ratpack-gradle:2.0.0-rc-1"
  }
}

apply plugin: "io.ratpack.ratpack-groovy"

repositories {
  mavenCentral()
}

dependencies {
  implementation ratpack.dependency("dropwizard-metrics")
}

Using ratpack.dependency("dropwizard-metrics") is equivalent to "io.ratpack:ratpack-dropwizard-metrics:«version of ratpack-gradle dependency»". This is the recommended way to add dependencies that are part of the core distribution.

The 'io.ratpack.ratpack-java' plugin adds the following implicit dependencies:

The 'io.ratpack.ratpack-groovy' plugin adds the following implicit dependencies:

The available libraries can be browsed via search.maven.org. All Ratpack jars are published to Maven Central.

3.23 The ‘application’ plugin

Both the 'ratpack-java' and 'ratpack-groovy' plugins also apply the core Gradle 'application' plugin. This plugin provides the ability to create a standalone executable distribution of your software. This is the preferred deployment format for Ratpack applications.

The 'application' plugin requires the main class (i.e. entry point) of your application to be specified. You must configure the 'mainClassName' attribute in your Gradle build file to be the fully qualified class name of class that contains a 'static void main(String[] args)' method which configures the Ratpack server. This is preconfigured by the 'ratpack-groovy' plugin to be the GroovyRatpackMain. This can be changed if you wish to use a custom entry point (consult the 'application' plugin documentation).

4.23 The ‘shadow’ plugin

Both the 'ratpack-java' and 'ratpack-groovy' plugins ship with integration support for the 3rd party 'shadow' plugin. This plugin provides the ability to create a self-contained “fat-jar” that includes your ratpack application and any compile and runtime dependencies.

The plugins react to the application of the 'shadow' plugin and configure additional task dependencies. They do not apply the 'shadow' plugin and, for compatibility reasons, do not ship with a version of the 'shadow' as a dependency.

To use the 'shadow' integration, you will need to include the dependency in your project and apply the plugin.

buildscript {
  repositories {
    mavenCentral()
    gradlePluginPortal()
  }
  dependencies {
    classpath "io.ratpack:ratpack-gradle:2.0.0-rc-1"
    classpath 'gradle.plugin.com.github.johnrengelman:shadow:7.1.2'
  }
}

apply plugin: "io.ratpack.ratpack-java"
apply plugin: 'com.github.johnrengelman.shadow'

repositories {
  mavenCentral()
}

The latest version of the 'shadow' plugin can be found on the project’s Github page.

You can now have the build generate the fat-jar, by running…

./gradlew shadowJar

5.23 The base dir

The base dir is effectively the root of the filesystem for the application. At build time, this is effectively the main set of resources for your application (i.e. src/main/resources). The Ratpack plugin adds a complimentary source of main resources, src/ratpack. You can choose not to use this dir, using src/main/resources instead, or changing its location via the ratpack.baseDir property in the Gradle build.

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "io.ratpack:ratpack-gradle:2.0.0-rc-1"
  }
}

apply plugin: "io.ratpack.ratpack-groovy"

repositories {
  mavenCentral()
}

ratpack.baseDir = file('ratpack')

When packaging as a distribution, the plugin will create a directory called app within the distribution that contains all the main resources of the project. This directory will be prepended to the classpath when the app is launched via the start scripts. This allows the application to read files from the base dir directly from disk instead of decompressing on the fly from the JAR. This is more efficient.

See Launching for more information.

1.5.23 The ‘ratpack.groovy’ script

The 'ratpack-groovy' plugin expects the main application definition to be located at either ratpack.groovy or Ratpack.groovy within the base dir. By default, it will effectively look in src/main/resources and src/ratpack. This file should not go into src/main/groovy as the application manages compilation of this file. Therefore, it needs to be on the classpath in source form (i.e. as a .groovy file) and not in compiled form.

See Groovy for more information about the contents of this file.

6.23 Running the application

The 'application' plugin provides the 'run' task for starting the Ratpack application. This is a task of the core Gradle JavaExec type. The 'ratpack-java' plugin configures this 'run' task to launch with the system property 'ratpack.development' set to true.

If you wish to set extra system properties for development time execution, you can configure this task…

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "io.ratpack:ratpack-gradle:2.0.0-rc-1"
  }
}

apply plugin: "io.ratpack.ratpack-java"

repositories {
  mavenCentral()
}

run {
  systemProperty "app.dbPassword", "secret"
}

1.6.23 Development time reloading

The Ratpack Gradle plugins integrate with Gradle’s Continuous Build feature. To leverage this, you can run the run task with the --continuous (or -t) argument.

Any changes made to source or resources will be compiled and processed and the application reloaded as a result.

2.6.23 Running with the ‘shadow’ plugin

If applied to the project, the 'shadow' plugin provides the 'runShadow' task for starting the Ratpack application from the fat-jar. Like the 'run' task, this is a task of the core Gradle JavaExec type. The 'shadow' plugin configure this 'runShadow' task to start the process using the java -jar <path/to/shadow-jar.jar> command.

Class reloading is not supported through the 'runShadow' task because the application is being run from the packaged jar file.

Extra system properties or JVM options can be configured on this task…

buildscript {
  repositories {
    mavenCentral()
    gradlePluginPortal()
  }
  dependencies {
    classpath "io.ratpack:ratpack-gradle:2.0.0-rc-1"
    classpath "gradle.plugin.com.github.johnrengelman:shadow:7.1.2"
  }
}

apply plugin: "io.ratpack.ratpack-java"
apply plugin: "com.github.johnrengelman.shadow"

repositories {
  mavenCentral()
}

runShadow {
  systemProperty "app.dbPassword", "secret"
}