The War Plugin

The War plugin extends the Java plugin to add support for assembling web application WAR files. It adds a default war task that assembles the WAR archive, and a web software component for publishing it.

Usage

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

build.gradle.kts

plugins {
    war
}

build.gradle

plugins {
    id 'war'
}

Project layout

In addition to the standard Java project layout, the War Plugin adds:

src/main/webapp: Web application sources

Tasks

The War plugin adds and modifies the following tasks:

war — War: Depends on: classes

Assembles the WAR archive containing the compiled classes, the web application content, and the runtime libraries.
assemble - lifecycle task: Depends on: war

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

Figure 1. War plugin - tasks

Dependency management

The War plugin adds two dependency configurations:

providedCompile: This configuration should be used for dependencies required at compilation but which are provided by the environment in which the WAR is deployed. Dependencies declared here are visible to the main and test compile and runtime classpaths, but are excluded from the WAR archive.
providedRuntime: This configuration should be used for dependencies required at runtime but which are provided by the environment in which the WAR is deployed. Dependencies declared here are visible to the main and test runtime classpaths, but are excluded from the WAR archive.

It is important to note that these 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 implementation configuration.

If you don’t want this transitive behavior, simply declare your provided dependencies like commons-httpclient:commons-httpclient:3.0@jar.

Publishing

components.web: A SoftwareComponent for publishing the production WAR created by the war task.

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 copied to WEB-INF/classes. The libraries on the runtimeClasspath configuration, minus those declared in the providedRuntime configuration, are copied to WEB-INF/lib.

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

The most commonly configured properties of the War task are:

webAppDirectory — DirectoryProperty

The directory whose contents are copied to the root of the archive. The war plugin sets the default value to src/main/webapp.

classpath — FileCollection

The classpath to include in the archive. Directories on the classpath are added to WEB-INF/classes and JAR or ZIP files are added to WEB-INF/lib. The war plugin sets the default value to sourceSets.main.runtimeClasspath minus the providedRuntime configuration.

webXml — File

The web.xml file to copy to WEB-INF/web.xml. When not set, no web.xml file is included in the archive.

An incubating replacement, webXmlFile (a RegularFileProperty), was introduced in Gradle 9.7.0.

webInf

Adds a nested CopySpec whose contents are copied into the WEB-INF directory of the archive.

Customizing

Here is an example with the most important customization options:

build.gradle.kts

repositories {
    mavenCentral()
}

dependencies {
    providedCompile("javax.servlet:servlet-api:2.5")
}

tasks.war {
    webAppDirectory = file("src/main/webapp")
    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.
    webXml = file("src/someWeb.xml") // copies a file to WEB-INF/web.xml
}

build.gradle

repositories {
    mavenCentral()
}

dependencies {
    providedCompile "javax.servlet:servlet-api:2.5"
}

war {
    webAppDirectory = file('src/main/webapp')
    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.
    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.