# Chapter 51. The Application Plugin

The Application plugin facilitates creating an executable JVM application. It makes it easy to start the application locally during development, and to package the application as a TAR and/or ZIP including operating system specific start scripts.

Applying the Application plugin also implicitly applies the Java plugin. The `main` source set is effectively the “application”.

Applying the Application plugin also implicitly applies the Distribution plugin. A `main` distribution is created that packages up the application, including code dependencies and generated start scripts.

## 51.1. Usage

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

Example 51.1. Using the application plugin

`build.gradle`

    apply plugin: 'application'

The only mandatory configuration for the plugin is the specification of the main class (i.e. entry point) of the application.

Example 51.2. Configure the application main class

`build.gradle`

    mainClassName = "org.gradle.sample.Main"

You can run the application by executing the `run` task (type: `JavaExec`). This will compile the main source set, and launch a new JVM with its classes (along with all runtime dependencies) as the classpath and using the specified main class. You can launch the application in debug mode with `gradle run --debug-jvm` (see `JavaExec.setDebug(boolean)`).

If your 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 51.3. Configure default JVM settings

`build.gradle`

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

### 51.1.1. The distribution

A distribution of the application can be created, by way of the Distribution plugin (which is automatically applied). A `main` distribution is created with the following content:

Table 51.1. Distribution content

Location | Content
(root dir) | `src/dist`
`lib` | All runtime dependencies and main source set class files.
`bin` | Start scripts (generated by `createStartScripts` task).

Static files to be added to the distribution can be simply added to `src/dist`. More advanced customization can be done by configuring the `CopySpec` exposed by the main distribution.

Example 51.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!")
        }
    }

    distributions {
        main {
            contents {
                from(createDocs) {
                    into "docs"
                }
            }
        }
    }

By specifying that the distribution should include the task's output files (see Section 18.9.1, “Task 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 51.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

You can run `gradle installDist` to create an image of the application in `build/install/`projectName``. You can run `gradle distZip` to create a ZIP containing the distribution, `gradle distTar` to create an application TAR or `gradle assemble` to build both.

### 51.1.2. Customizing start script generation

The application plugin can generate Unix (suitable for Linux, Mac OS X etc.) and Windows start scripts out of the box. The start scripts launch a JVM with the specified settings defined as part of the original build and runtime environment (e.g. `JAVA_OPTS` env var). The default script templates are based on the same scripts used to launch Gradle itself, that ship as part of a Gradle distribution.

The start scripts are completely customizable. Please refer to the documentation of `CreateStartScripts` for more details and customization examples.

## 51.2. Tasks

The Application plugin adds the following tasks to the project.

Table 51.2. 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.
`installDist` | `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.

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