# The War Plugin

version 7.6.6-20251025033327+0000

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.

## Usage

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

Example 1. Using the War plugin
build.gradle

    plugins {
        id 'war'
    }

build.gradle.kts

    plugins {
        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: `compile`

  Assembles the application WAR file.

`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 thus visible to the `main` and `test` compilation classpaths.

`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 only visible to the `main` and `test` runtime classpaths.

| 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.

## Convention properties (deprecated)

`webAppDirName` — `String`

  Default value: `src/main/webapp`

  The name of the web application source directory, relative to the project directory.

`webAppDir` — (read-only) `File`

  Default value: `$webAppDirName`, e.g. src/main/webapp

  The path to the web application source directory.

These properties are provided by a WarPluginConvention object.

Configuring war tasks via convention properties is deprecated. If you need to set default values the `war` task then configure the task directly. If you want to configure all tasks of type `War` in the project then use tasks.withType(War.class).configureEach(…​).

## 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` [1] configuration are copied to `WEB-INF/lib`.

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

## Customizing

Here is an example with the most important customization options:

Example 2. Customization of war plugin
build.gradle

    configurations {
       moreLibs
    }

    repositories {
       flatDir { dirs "lib" }
       mavenCentral()
    }

    dependencies {
        implementation 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"
        }
        runtimeOnly ":runtime:1.0"
        providedRuntime ":providedRuntime:1.0@jar"
        testImplementation "junit:junit:4.13"
        moreLibs ":otherLib:1.0"
    }

    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.
        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
    }

build.gradle.kts

    val moreLibs = configurations.create("moreLibs")

    repositories {
        flatDir { dir("lib") }
        mavenCentral()
    }

    dependencies {
        implementation(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")
        })
        runtimeOnly(":runtime:1.0")
        providedRuntime(":providedRuntime:1.0@jar")
        testImplementation("junit:junit:4.13")
        moreLibs(":otherLib:1.0")
    }

    tasks.war {
        webAppDirectory.set(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.
        classpath(fileTree("additionalLibs")) // adds a file-set to the WEB-INF/lib dir.
        classpath(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.

1. The `runtime` configuration extends the `compile` configuration.