# Chapter 45. The Application Plugin

The Gradle application plugin extends the language plugins with common application related tasks. It allows running and bundling applications for the jvm.

## 45.1. Usage

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

Example 45.1. Using the application plugin

`build.gradle`

    apply plugin:'application'

To define the main-class for the application you have to set the `mainClassName` property as shown below

Example 45.2. Configure the application main class

`build.gradle`

    mainClassName = "org.gradle.sample.Main"

Then, you can run the application by running `gradle run`. Gradle will take care of building the application classes, along with their runtime dependencies, and starting the application with the correct classpath. You can launch the application in debug mode with `gradle run --debug-jvm` (see `JavaExec.setDebug()`).

The plugin can also build a distribution for your application. The distribution will package up the runtime dependencies of the application along with some OS specific start scripts. All files stored in `src/dist` will be added to the root of the distribution. You can run `gradle installApp` to create an image of the application in `build/install/`projectName``. You can run `gradle distZip` to create a ZIP containing the distribution.

If your Java application requires a specific set of JVM settings or system properties, you can configure the `applicationDefaultJvmArgs` property. These JVM arguments are applied to the `run` task and also considered in the generated start scripts of your distribution.

Example 45.3. Configure default JVM settings

`build.gradle`

    applicationDefaultJvmArgs = ["-Dgreeting.language=en"]

## 45.2. Tasks

The Application plugin adds the following tasks to the project.

Table 45.1. Application plugin - tasks

Task name | Depends on | Type | Description
`run` | `classes` | `JavaExec` | Starts the application.
`startScripts` | `jar` | `CreateStartScripts` | Creates OS specific scripts to run the project as a JVM application.
`installApp` | `jar`, `startScripts` | `Sync` | Installs the application into a specified directory.
`distZip` | `jar`, `startScripts` | `Zip` | Creates a full distribution ZIP archive including runtime libraries and OS specific scripts.
`distTar` | `jar`, `startScripts` | `Tar` | Creates a full distribution TAR archive including runtime libraries and OS specific scripts.

## 45.3. Convention properties

The application plugin adds some properties to the project, which you can use to configure its behaviour. See the `Project` class in the API documentation.

## 45.4. Including other resources in the distribution

One of the convention properties added by the plugin is `applicationDistribution` which is a `CopySpec`. This specification is used by the `installApp` and `distZip` tasks as the specification of what is to be included in the distribution. In addition to copying the start scripts to the `bin` dir and necessary jars to `lib` in the distribution, all of the files from the `src/dist` directory are also copied. To include any static files in the distribution, simply arrange them in the `src/dist` directory.

If your project generates files to be included in the distribution, e.g. documentation, you can add these files to the distribution by adding to the `applicationDistribution` copy spec.

Example 45.4. Include output from other tasks in the application distribution

`build.gradle`

    task createDocs {
        def docs = file("$buildDir/docs")
        outputs.dir docs
        doLast {
            docs.mkdirs()
            new File(docs, "readme.txt").write("Read me!")
        }
    }

    applicationDistribution.from(createDocs) {
        into "docs"
    }

By specifying that the distribution should include the task's output files (see Section 15.9.1, “Declaring a task's inputs and outputs”), Gradle knows that the task that produces the files must be invoked before the distribution can be assembled and will take care of this for you.

Example 45.5. Automatically creating files for distribution

Output of `gradle distZip`

    > gradle distZip
    :createDocs
    :compileJava
    :processResources UP-TO-DATE
    :classes
    :jar
    :startScripts
    :distZip

    BUILD SUCCESSFUL

    Total time: 1 secs