【Gradle jvm插件系列3】 Java Application插件权威详解

应用程序插件

1. 构建JVM应用程序

使用应用程序插件可以方便地创建可执行的JVM应用程序。它使得在开发过程中可以轻松启动应用程序，并将应用程序打包成包含操作系统特定启动脚本的TAR和/或ZIP。

应用程序插件还隐式应用了Java插件。主要源集实际上是“application”。

应用程序插件还隐式应用了Distribution插件。它会创建一个主要分发，其中包含应用程序、代码依赖项和生成的启动脚本。

2. 构建JVM应用程序

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

plugins {
    id 'application'
}

插件的唯一必需配置是指定**应用程序的主类（**即入口点）。

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任务，并考虑在分发的生成启动脚本中。

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

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

application {
    executableDir = 'custom_bin_dir'
}

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

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

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

其次，您需要告诉Gradle要运行的模块的名称，除了主类名之外，像这样：

application {
    mainModule = 'org.gradle.sample.app' // 在module-info.java中定义的名称
    mainClass = 'org.gradle.sample.Main'
}

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

配置的主类也被嵌入到应用程序Jar的module-info.class文件中。如果直接使用java命令运行模块化应用程序，则只需提供模块名即可。

您还可以查看一个已准备好的示例，其中包括多项目中的模块化应用程序。

4. 构建分发

可以通过Distribution插件（自动应用）创建应用程序的分发。主要分发包含以下内容：

• 根目录：src/dist、lib。所有运行时依赖项和主要源集类文件。
• bin：启动脚本（由startScripts任务生成）。

可以简单地将静态文件添加到src/dist以添加到分发中。更高级的定制可以通过配置主分发所暴露的CopySpec来完成。

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以构建两者。

5. 自定义启动脚本生成

应用程序插件可以自动生成Unix（适用于Linux、macOS等）和Windows启动脚本。启动脚本使用原始构建和运行时环境中定义的指定设置（例如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存档。

6.应用程序扩展

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

您可以通过先前显示的application {}块来配置扩展，例如在构建脚本中使用以下内容：

application {
    executableDir = 'custom_bin_dir'
}

7.启动脚本的许可证

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

8.约定属性（已弃用）

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

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

application.applicationName = 'my-app'

参考链接

小军李：【Gradle jvm插件系列1】 Java Application插件权威详解

小军李：【Gradle jvm插件系列2】 Java Library插件用法示例权威详解

小军李：【Gradle jvm插件系列3】 Java platform平台插件权威详解

小军李：【Gradle jvm插件系列4】 scala插件权威详解

小军李：【gradle多模块系列1】多项目构建和子项目的添加管理

小军李：【Gradle多模块系列2】在子项目之间声明依赖关系和共享构建逻辑示例详解

小军李：【Gradle 多模块系列3】如何开发自定义Gradle插件

小军李：【Gradle多模块系列4】JVM项目的依赖管理