Chapter 50. The War Plugin

Table of Contents

50.1. Usage
50.2. Tasks
50.3. Project layout
50.4. Dependency management
50.5. Convention properties
50.6. War
50.7. Customizing

The War plugin extends the Java plugin to add support for assembling web application WAR files. It disables the default JAR archive generation of the Java plugin and adds a default WAR archive task.

50.1. Usage

To use the War plugin, include the following in your build script:

Example 50.1. Using the War plugin


apply plugin: 'war'

50.2. Tasks

The War plugin adds the following tasks to the project.

Table 50.1. War plugin - tasks

Task name Depends on Type Description
war compile War Assembles the application WAR file.

The War plugin adds the following dependencies to tasks added by the Java plugin.

Table 50.2. War plugin - additional task dependencies

Task nameDepends on
assemble war

Figure 50.1. War plugin - tasks

War plugin - tasks

50.3. Project layout

Table 50.3. War plugin - project layout

Directory Meaning
src/main/webapp Web application sources

50.4. Dependency management

The War plugin adds two dependency configurations named providedCompile and providedRuntime. Those two configurations have the same scope as the respective compile and runtime configurations, except that they are not added to the WAR archive. It is important to note that those provided configurations work transitively. Let's say you add commons-httpclient:commons-httpclient:3.0 to any of the provided configurations. This dependency has a dependency on commons-codec. Because this is a “provided” configuration, this means that neither of these dependencies will be added to your WAR, even if the commons-codec library is an explicit dependency of your compile configuration. If you don't want this transitive behavior, simply declare your provided dependencies like commons-httpclient:commons-httpclient:3.0@jar.

50.5. Convention properties

Table 50.4. War plugin - directory properties

Property name Type Default value Description
webAppDirName String src/main/webapp The name of the web application source directory, relative to the project directory.
webAppDir File (read-only) projectDir/webAppDirName The web application source directory.

These properties are provided by a WarPluginConvention convention object.

50.6. War

The default behavior of the War task is to copy the content of src/main/webapp to the root of the archive. Your webapp directory may of course contain a WEB-INF sub-directory, which may contain a web.xml file. Your compiled classes are compiled to WEB-INF/classes. All the dependencies of the runtime [28] configuration are copied to WEB-INF/lib.

The War class in the API documentation has additional useful information.

50.7. Customizing

Here is an example with the most important customization options:

Example 50.2. Customization of war plugin


configurations {

repositories {
   flatDir { dirs "lib" }

dependencies {
    compile module(":compile:1.0") {
        dependency ":compile-transitive-1.0@jar"
        dependency ":providedCompile-transitive:1.0@jar"
    providedCompile "javax.servlet:servlet-api:2.5"
    providedCompile module(":providedCompile:1.0") {
        dependency ":providedCompile-transitive:1.0@jar"
    runtime ":runtime:1.0"
    providedRuntime ":providedRuntime:1.0@jar"
    testCompile "junit:junit:4.12"
    moreLibs ":otherLib:1.0"

war {
    from 'src/rootContent' // adds a file-set to the root of the archive
    webInf { from 'src/additionalWebInf' } // adds a file-set to the WEB-INF dir.
    classpath fileTree('additionalLibs') // adds a file-set to the WEB-INF/lib dir.
    classpath configurations.moreLibs // adds a configuration to the WEB-INF/lib dir.
    webXml = file('src/someWeb.xml') // copies a file to WEB-INF/web.xml

Of course one can configure the different file-sets with a closure to define excludes and includes.

[28] The runtime configuration extends the compile configuration.