Gradle Cargo 插件技术文档

1. 安装指南

1.1 添加插件到构建脚本

要使用 Gradle Cargo 插件，首先需要将其二进制文件添加到构建脚本的类路径中。插件可以在 Gradle 插件门户中找到。以下代码片段展示了如何使用 buildscript 语法来获取插件：

buildscript {
    repositories {
        gradlePluginPortal()
    }

    dependencies {
        classpath 'com.bmuschko:gradle-cargo-plugin:2.9.0'
    }
}

1.2 应用插件

插件 JAR 文件包含两个插件：

• com.bmuschko.cargo-base：提供 Cargo 自定义任务类型、预配置类路径和部署项。
• com.bmuschko.cargo：提供一组本地和远程 Cargo 任务，并公开扩展以进行配置。

大多数用户会选择使用 com.bmuschko.cargo 插件，因为它可以快速上手。以下是应用该插件的代码示例：

apply plugin: 'com.bmuschko.cargo'

如果你需要完全控制部署任务，可以使用 com.bmuschko.cargo-base 插件。以下是应用该插件的代码示例：

apply plugin: 'com.bmuschko.cargo-base'

1.3 配置 Cargo 版本

com.bmuschko.cargo-base 插件已经为 Cargo 设置了依赖项，并选择了一个默认版本的库。你也可以定义自定义版本的 Cargo 库。以下示例展示了如何使用 Cargo 1.9.10 版本：

dependencies {
    def cargoVersion = '1.9.10'
    cargo "org.codehaus.cargo:cargo-core-uberjar:$cargoVersion",
          "org.codehaus.cargo:cargo-licensed-dtds:$cargoVersion",
          "org.codehaus.cargo:cargo-ant:$cargoVersion"
}

2. 项目使用说明

2.1 插件功能

Gradle Cargo 插件通过利用 Cargo Ant 任务，为任何给定的 Gradle 构建提供了将 Web 应用程序部署到本地和远程容器的能力。该插件支持 WAR 和 EAR 工件。

2.2 典型用例

该插件的典型用例是支持开发过程中的部署。需要注意的是，Cargo 使用热部署，随着时间的推移，这会填满运行容器的 JVM 进程的 PermGen 内存，最终导致 java.lang.OutOfMemoryError。

2.3 容器管理

Cargo 支持通过 Cargo daemon 进行容器管理（启动/停止远程容器）。然而，在持续部署场景中，通常需要执行更复杂的操作。

3. 项目 API 使用文档

3.1 预定义任务

cargo 插件预定义了以下任务：

任务名称	依赖任务	类型	描述
cargoDeployRemote	-	CargoDeployRemote	将可部署项部署到远程容器。
cargoUndeployRemote	-	CargoUndeployRemote	从远程容器中取消部署可部署项。
cargoRedeployRemote	-	CargoRedeployRemote	重新部署可部署项到远程容器。
cargoRunLocal	-	CargoRunLocal	启动本地容器，部署可部署项并等待停止。
cargoStartLocal	-	CargoStartLocal	启动本地容器，部署可部署项并执行任务。
cargoRedeployLocal	-	CargoRedeployLocal	在本地容器上重新部署可部署项。
cargoStopLocal	-	CargoStopLocal	停止本地容器。
cargoConfigureLocal	-	CargoConfigureLocal	配置本地容器。

3.2 扩展属性

cargo 插件定义了以下约定属性：

• containerId：目标容器的 ID。
• port：容器响应的 TCP 端口（默认为 8080）。

你可以在 cargo 闭包中定义 1..n 个部署工件的可选属性，每个部署工件在其自己的闭包中指定：

• file：可以传递给 Project.files(Object...) 的任何类型，并解析为单个文件或目录。
• context：容器处理 Web 应用程序的 URL 上下文（默认为 WAR/EAR 名称）。

4. 项目安装方式

4.1 本地安装

要安装本地容器，可以使用 cargoRunLocal 或 cargoStartLocal 任务。以下是一个示例：

cargo {
    containerId = 'tomcat9x'
    port = 8080

    local {
        jvmArgs = '-Xmx512m'
        outputFile = file('build/output.log')
        logFile = file('build/cargo.log')
        logLevel = 'high'
    }
}

4.2 远程安装

要安装远程容器，可以使用 cargoDeployRemote 任务。以下是一个示例：

cargo {
    containerId = 'tomcat9x'
    port = 8080

    remote {
        protocol = 'http'
        hostname = 'remote-server'
        username = 'admin'
        password = 'password'
    }
}

通过以上步骤，你可以成功安装并使用 Gradle Cargo 插件进行本地和远程容器的部署。