应用程序插件有助于创建可执行 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)来运行应用程序。这将编译主源集,并使用其类(以及所有运行时依赖项)作为类路径,并使用指定的 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 任务,并在您分发的生成启动脚本中考虑。

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

配置的主类也烘焙到应用程序 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 installDist 以在 build/install/projectName 中创建应用程序映像。您可以运行 gradle distZip 以创建包含发行版的 ZIP,运行 gradle distTar 以创建应用程序 TAR,或运行 gradle assemble 以同时构建两者。

自定义启动脚本生成

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

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

任务

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

runJavaExec

依赖于classes

启动应用程序。

startScriptsCreateStartScripts

依赖于jar

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

installDistSync

依赖于jarstartScripts

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

distZipZip

依赖于jarstartScripts

创建完整的发布 ZIP 存档,包括运行时库和特定于操作系统的脚本。

distTarTar

依赖于jarstartScripts

创建完整的发布 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'