Chapter 69. Building Play applications

To use the Play plugin, include the following in your build script to apply the play plugin and add the Typesafe repositories:

plugins {
    id 'play'
}

repositories {
    jcenter()
    maven {
        name "typesafe-maven-release"
        url "https://repo.typesafe.com/typesafe/maven-releases"
    }
    ivy {
        name "typesafe-ivy-release"
        url "https://repo.typesafe.com/typesafe/ivy-releases"
        layout "ivy"
    }
}

Note that defining the Typesafe repositories is necessary. In future versions of Gradle, this will be replaced with a more convenient syntax.

The Play plugin currently has a few limitations.

The Play plugin uses a software model to describe a Play application and how to build it. The Play software model extends the base Gradle software model to add support for building Play applications. A Play application is represented by a PlayApplicationSpec component type. The plugin automatically creates a single PlayApplicationBinarySpec instance when it is applied. Additional Play components cannot be added to a project.

Figure 69.1. Play plugin - software model

The Play plugin follows the typical Play application layout. You can configure source sets to include additional directories or change the defaults.

├── app                 → Application source code.
│   ├── assets          → Assets that require compilation.
│   │   └── javascripts → JavaScript source code to be minified.
│   ├── controllers     → Application controller source code.
│   ├── models          → Application business source code.
│   └── views           → Application UI templates.
├── build.gradle        → Your project's build script.
├── conf                → Main application configuration file and routes files.
├── public              → Public assets.
│   ├── images          → Application image files.
│   ├── javascripts     → Typically JavaScript source code.
│   └── stylesheets     → Typically CSS source code.
└── test                → Test source code.

The Play plugin hooks into the normal Gradle lifecycle tasks such as assemble, check and build, but it also adds several additional tasks which form the lifecycle of a Play project:

The plugin also provides tasks for running, testing and packaging your Play application:

For the different types of sources in a Play application, the plugin adds the following compilation tasks:

Gradle provides a report that you can run from the command-line that shows some details about the components and binaries that your project produces. To use this report, just run gradle components. Below is an example of running this report for one of the sample projects:

> gradle components
:components

------------------------------------------------------------
Root project
------------------------------------------------------------

Play Application 'play'
-----------------------

Source sets
    Java source 'play:java'
        srcDir: app
        includes: **/*.java
    JavaScript source 'play:javaScript'
        srcDir: app/assets
        includes: **/*.js
    JVM resources 'play:resources'
        srcDir: conf
    Routes source 'play:routes'
        srcDir: conf
        includes: routes, *.routes
    Scala source 'play:scala'
        srcDir: app
        includes: **/*.scala
    Twirl template source 'play:twirlTemplates'
        srcDir: app
        includes: **/*.html

Binaries
    Play Application Jar 'play:binary'
        build using task: :playBinary
        target platform: Play Platform (Play 2.3.9, Scala: 2.11, Java: Java SE 8)
        toolchain: Default Play Toolchain
        classes dir: build/playBinary/classes
        resources dir: build/playBinary/resources
        JAR file: build/playBinary/lib/basic.jar

Note: currently not all plugins register their components, so some components may not be visible here.

BUILD SUCCESSFUL

Total time: 1 secs

The runPlayBinary task starts the Play application under development. During development it is beneficial to execute this task as a continuous build. Continuous build is a generic feature that supports automatically re-running a build when inputs change. The runPlayBinary task is “continuous build aware” in that it behaves differently when run as part of a continuous build.

When not run as part of a continuous build, the runPlayBinary task will block the build. That is, the task will not complete as long as the application is running. When running as part of a continuous build, the task will start the application if not running and otherwise propagate any changes to the code of the application to the running instance. This is useful for quickly iterating on your Play application with an edit->rebuild->refresh cycle. Changes to your application will not take affect until the end of the overall build.

To enable continuous build, run Gradle with -t runPlayBinary or --continuous runPlayBinary.

Users of Play used to such a workflow with Play's default build system should note that compile errors are handled differently. If a build failure occurs during a continuous build, the Play application will not be reloaded. Instead, you will be presented with an exception message. The exception message will only contain the overall cause of the build failure. More detailed information will only be available from the console.

Play applications can be built in multi-project builds as well. Simply apply the play plugin in the appropriate subprojects and create any project dependencies on the play configuration.

dependencies {
    play project(":admin")
    play project(":user")
    play project(":util")
}

See the play/multiproject sample provided in the Gradle distribution for a working example.

Gradle provides the capability to package your Play application so that it can easily be distributed and run in a target environment. The distribution package (zip file) contains the Play binary jars, all dependencies, and generated scripts that set up the classpath and run the application in a Play-specific Netty container.

The distribution can be created by running the dist lifecycle task and places the distribution in the $buildDir/distributions directory. Alternatively, one can validate the contents by running the stage lifecycle task which copies the files to the $buildDir/stage directory using the layout of the distribution package.

model {
    distributions {
        playBinary {
            contents {
                from("README.md")
                from("scripts") {
                    into "bin"
                }
            }
        }
    }
}

If you want to generate IDE metadata configuration for your Play project, you need to apply the appropriate IDE plugin. Gradle supports generating IDE metadata for IDEA only for Play projects at this time.

To generate IDEA's metadata, apply the idea plugin along with the play plugin.

plugins {
    id 'play'
    id 'idea'
}

Source code generated by routes and Twirl templates cannot be generated by IDEA directly, so changes made to those files will not affect compilation until the next Gradle build. You can run the Play application with Gradle in continuous build to automatically rebuild and reload the application whenever something changes.

For additional information about developing Play applications: