# The War Plugin

version 9.8.0-20260811015503+0000

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.