Application 插件方便创建可执行的 JVM 应用程序。它可以轻松地在开发期间在本地启动应用程序,并将应用程序打包为 TAR 和/或 ZIP,包括操作系统特定的启动脚本。

应用 Application 插件也会隐式地应用 Java 插件main 源代码集实际上就是“应用程序”。

应用 Application 插件也会隐式地应用 Distribution 插件。将创建一个 main 分发包,其中打包了应用程序,包括代码依赖项和生成的启动脚本。

构建 JVM 应用程序

要使用 Application 插件,请在您的构建脚本中包含以下内容

build.gradle.kts
plugins {
    application
}
build.gradle
plugins {
    id 'application'
}

插件的唯一强制配置是应用程序主类(即入口点)的规范。

build.gradle.kts
application {
    mainClass = "org.gradle.sample.Main"
}
build.gradle
application {
    mainClass = 'org.gradle.sample.Main'
}

您可以通过执行 run task(类型:JavaExec)来运行应用程序。这将编译 main 源代码集,并启动一个新的 JVM,将其类(以及所有运行时依赖项)作为类路径,并使用指定的主类。您可以使用 gradle run --debug-jvm 在调试模式下启动应用程序(请参阅 JavaExec.setDebug(boolean))。

自 Gradle 4.9 起,命令行参数可以使用 --args 传递。例如,如果您想使用命令行参数 foo --bar 启动应用程序,您可以使用 gradle run --args="foo --bar"(请参阅 JavaExec.setArgsString(java.lang.String)

如果您的应用程序需要一组特定的 JVM 设置或系统属性,您可以配置 applicationDefaultJvmArgs 属性。这些 JVM 参数应用于 run task,并在您的分发包的生成的启动脚本中考虑。

build.gradle.kts
application {
    applicationDefaultJvmArgs = listOf("-Dgreeting.language=en")
}
build.gradle
application {
    applicationDefaultJvmArgs = ['-Dgreeting.language=en']
}

如果您的应用程序的启动脚本应位于与 bin 不同的目录中,您可以配置 executableDir 属性。

build.gradle.kts
application {
    executableDir = "custom_bin_dir"
}
build.gradle
application {
    executableDir = 'custom_bin_dir'
}

使用 Java 模块系统构建应用程序

Gradle 支持构建 Java 模块,如 Java Library 插件文档的相应部分所述。Java 模块也可以是可运行的,您可以使用 Application 插件来运行和打包这样的模块化应用程序。为此,除了非模块化应用程序的操作外,您还需要做两件事。

首先,您需要添加一个 module-info.java 文件来描述您的应用程序模块。有关此主题的更多详细信息,请参阅 Java Library 插件文档

其次,您需要告诉 Gradle 您要运行的模块名称以及主类名称,如下所示

build.gradle.kts
application {
    mainModule = "org.gradle.sample.app" // name defined in module-info.java
    mainClass = "org.gradle.sample.Main"
}
build.gradle
application {
    mainModule = 'org.gradle.sample.app' // name defined in module-info.java
    mainClass = 'org.gradle.sample.Main'
}

就是这样。如果您通过执行 run task 或通过 生成的启动脚本 运行您的应用程序,它将作为模块运行,并在运行时遵守模块边界。例如,从另一个模块反射访问内部包可能会失败。

配置的主类也被烘焙到您的应用程序 Jar 的 module-info.class 文件中。如果您直接使用 java 命令运行模块化应用程序,那么仅提供模块名称就足够了。

您还可以查看 现成的示例,其中包含作为多项目一部分的模块化应用程序。

构建分发包

可以通过 Distribution 插件(自动应用)创建应用程序的分发包。将创建一个包含以下内容的 main 分发包

表 1. 分发包内容
位置 内容

(根目录)

src/dist

lib

所有运行时依赖项和 main 源代码集类文件。

bin

启动脚本(由 startScripts task 生成)。

要添加到分发包的静态文件可以简单地添加到 src/dist。更高级的自定义可以通过配置 main 分发包公开的 CopySpec 来完成。

build.gradle.kts
val createDocs by tasks.registering {
    val docs = layout.buildDirectory.dir("docs")
    outputs.dir(docs)
    doLast {
        docs.get().asFile.mkdirs()
        docs.get().file("readme.txt").asFile.writeText("Read me!")
    }
}

distributions {
    main {
        contents {
            from(createDocs) {
                into("docs")
            }
        }
    }
}
build.gradle
tasks.register('createDocs') {
    def docs = layout.buildDirectory.dir('docs')
    outputs.dir docs
    doLast {
        docs.get().asFile.mkdirs()
        docs.get().file('readme.txt').asFile.write('Read me!')
    }
}

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

通过指定分发包应包含 task 的输出文件(请参阅 增量构建),Gradle 知道必须在组装分发包之前调用生成文件的 task,并将为您处理此事。

您可以运行 gradle installDist 以在 build/install/projectName 中创建应用程序的镜像。您可以运行 gradle distZip 以创建包含分发包的 ZIP 文件,运行 gradle distTar 以创建应用程序 TAR 文件,或运行 gradle assemble 以构建两者。

自定义启动脚本生成

Application 插件可以开箱即用地生成 Unix(适用于 Linux、macOS 等)和 Windows 启动脚本。启动脚本使用指定的设置(定义为原始构建和运行时环境的一部分)启动 JVM(例如 JAVA_OPTS 环境变量)。默认脚本模板基于用于启动 Gradle 本身的相同脚本,这些脚本作为 Gradle 分发包的一部分发布。

启动脚本是完全可自定义的。有关更多详细信息和自定义示例,请参阅 CreateStartScripts 的文档。

Tasks

Application 插件向项目添加以下 task。

runJavaExec

依赖于classes

启动应用程序。

startScriptsCreateStartScripts

依赖于jar

创建特定于操作系统的脚本以将项目作为 JVM 应用程序运行。

installDistSync

依赖于jar, startScripts

将应用程序安装到指定目录。

distZipZip

依赖于jar, startScripts

创建包含完整分发包的 ZIP 归档文件,包括运行时库和特定于操作系统的脚本。

distTarTar

依赖于jar, startScripts

创建包含完整分发包的 TAR 归档文件,包括运行时库和特定于操作系统的脚本。

Application 扩展

Application 插件向项目添加一个扩展,您可以使用它来配置其行为。有关扩展上可用属性的更多信息,请参阅 JavaApplication DSL 文档。

您可以通过之前显示的 application {} 代码块配置扩展,例如在您的构建脚本中使用以下内容

build.gradle.kts
application {
    executableDir = "custom_bin_dir"
}
build.gradle
application {
    executableDir = 'custom_bin_dir'
}

启动脚本的许可证

为应用程序生成的启动脚本在 Apache 2.0 软件许可证 下获得许可。

约定属性(已弃用)

此插件还向项目添加了一些约定属性,您可以使用它们来配置其行为。这些属性是已弃用的,并已被上面描述的扩展取代。有关它们的更多信息,请参阅 Project DSL 文档。

与扩展属性不同,这些属性在构建脚本中显示为顶级项目属性。例如,要更改应用程序名称,您只需将以下内容添加到您的构建脚本中

build.gradle.kts
application.applicationName = "my-app"
build.gradle
application.applicationName = 'my-app'