应用插件有助于创建可执行的 JVM 应用程序。它使得在开发过程中在本地启动应用程序以及将应用程序打包为 TAR 和/或 ZIP(包括特定于操作系统的启动脚本)变得容易。

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

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

构建 JVM 应用程序

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

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 任务(类型:JavaExec)来运行应用程序。这将编译主源集,并启动一个新的 JVM,其类(以及所有运行时依赖项)作为 classpath 并使用指定的主类。您可以使用 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 任务,并在分发包生成的启动脚本中也考虑在内。

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 库插件文档的相应部分 中所述。Java 模块也可以是可运行的,您可以使用应用插件来运行和打包此类模块化应用程序。为此,除了对非模块化应用程序执行的操作之外,您还需要做两件事。

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

其次,您需要告诉 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 任务或通过 生成的启动脚本 运行您的应用程序,它将作为模块运行并遵守运行时的模块边界。例如,从另一个模块反射访问内部包可能会失败。

配置的 main class 也烘焙到您的应用程序 Jar 的 module-info.class 文件中。如果您直接使用 java 命令运行模块化应用程序,则只需提供模块名称。

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

构建分发包

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

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

(根目录)

src/dist

lib

所有运行时依赖项和主源集类文件。

bin

启动脚本(由 startScripts 任务生成)。

要添加到分发包中的静态文件可以简单地添加到 src/dist。更高级的自定义可以通过配置主分发包公开的 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'
            }
        }
    }
}

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

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

自定义启动脚本生成

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

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

任务

应用插件向项目添加以下任务。

runJavaExec

依赖于classes

启动应用程序。

startScriptsCreateStartScripts

依赖于jar

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

installDistSync

依赖于jar, startScripts

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

distZipZip

依赖于jar, startScripts

创建包含运行时库和 OS 特定脚本的完整分发 ZIP 存档。

distTarTar

依赖于jar, startScripts

创建包含运行时库和 OS 特定脚本的完整分发 TAR 存档。

应用扩展

应用插件向项目添加了一个扩展,您可以使用它来配置其行为。有关扩展上可用属性的更多信息,请参阅 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'