应用插件 - Gradle 构建系统

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

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

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

构建 JVM 应用

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

build.gradle.kts

plugins {
    application
}

build.gradle

plugins {
    id 'application'
}

插件唯一的强制性配置是指定应用的主类（即入口点）。

示例 2. 配置应用主类

build.gradle.kts

application {
    mainClass = "org.gradle.sample.Main"
}

build.gradle

application {
    mainClass = 'org.gradle.sample.Main'
}

您可以通过执行 run 任务（类型：JavaExec）来运行应用。这将编译主源集，并启动一个新的 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 任务，并在生成的分发包启动脚本中被考虑进去。

示例 3. 配置默认 JVM 设置

build.gradle.kts

application {
    applicationDefaultJvmArgs = listOf("-Dgreeting.language=en")
}

build.gradle

application {
    applicationDefaultJvmArgs = ['-Dgreeting.language=en']
}

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

示例 4. 配置自定义启动脚本目录

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 要运行的模块名称，如下所示

示例 5. 配置模块化应用的主模块

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 命令运行模块化应用，则只需提供模块名称即可。

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

构建分发包

可以通过 Distribution 插件（该插件会自动应用）创建应用的分发包。会创建一个包含以下内容的 main 分发包

表 1. 分发包内容
位置	内容
(根目录)	`src/dist`
`lib`	所有运行时依赖项和主源集类文件。
`bin`	启动脚本（由 `startScripts` 任务生成）。

要添加到分发包中的静态文件可以直接添加到 src/dist。可以通过配置主分发包公开的 CopySpec 进行更高级的自定义。

示例 6. 在应用分发包中包含其他任务的输出

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 启动脚本。启动脚本会启动一个 JVM，并使用原始构建和运行时环境（例如 JAVA_OPTS 环境变量）中定义的指定设置。默认脚本模板基于用于启动 Gradle 本身（作为 Gradle 分发包的一部分提供）的相同脚本。

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

任务

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

run — JavaExec: 依赖于: classes

启动应用。
startScripts — CreateStartScripts: 依赖于: jar

创建特定于操作系统的脚本以将项目作为 JVM 应用运行。
installDist — Sync: 依赖于: jar, startScripts

将应用安装到指定目录。
distZip — Zip: 依赖于: jar, startScripts

创建包含运行时库和特定于操作系统的脚本的完整分发 ZIP 归档文件。
distTar — Tar: 依赖于: jar, startScripts

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

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'

此页面有帮助吗？