复合构建是包含其他构建的构建。

structuring builds 4

复合构建类似于 Gradle 多项目构建,不同之处在于它包含的是整个 builds 而不是 subprojects

复合构建允许您

  • 组合通常独立开发的构建,例如,当尝试修复应用程序使用的库中的错误时。

  • 将大型多项目构建分解为更小、更隔离的块,可以根据需要独立或一起处理。

包含在复合构建中的构建称为 包含构建 。 包含构建不与复合构建或其他包含构建共享任何配置。 每个包含构建都以隔离方式配置和执行。

定义复合构建

以下示例演示了如何将两个通常独立开发的 Gradle 构建组合成复合构建。

my-composite
├── gradle
├── gradlew
├── settings.gradle.kts
├── build.gradle.kts
├── my-app
│   ├── settings.gradle.kts
│   └── app
│       ├── build.gradle.kts
│       └── src/main/java/org/sample/my-app/Main.java
└── my-utils
    ├── settings.gradle.kts
    ├── number-utils
    │   ├── build.gradle.kts
    │   └── src/main/java/org/sample/numberutils/Numbers.java
    └── string-utils
        ├── build.gradle.kts
        └── src/main/java/org/sample/stringutils/Strings.java

my-utils 多项目构建生成两个 Java 库,number-utilsstring-utilsmy-app 构建生成一个使用这些库中的函数的可执行文件。

my-app 构建不直接依赖于 my-utils。 相反,它声明对 my-utils 生成的库的二进制依赖。

my-app/app/build.gradle.kts
plugins {
    id("application")
}

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

dependencies {
    implementation("org.sample:number-utils:1.0")
    implementation("org.sample:string-utils:1.0")
}
my-app/app/build.gradle
plugins {
    id 'application'
}

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

dependencies {
    implementation 'org.sample:number-utils:1.0'
    implementation 'org.sample:string-utils:1.0'
}

通过 --include-build 定义复合构建

--include-build 命令行参数将执行的构建转换为复合构建,并将包含构建中的依赖项替换到执行的构建中。

例如,从 my-app 运行的 ./gradlew run --include-build ../my-utils 的输出

$ ./gradlew --include-build ../my-utils run
> Task :app:processResources NO-SOURCE
> Task :my-utils:string-utils:compileJava
> Task :my-utils:string-utils:processResources NO-SOURCE
> Task :my-utils:string-utils:classes
> Task :my-utils:string-utils:jar
> Task :my-utils:number-utils:compileJava
> Task :my-utils:number-utils:processResources NO-SOURCE
> Task :my-utils:number-utils:classes
> Task :my-utils:number-utils:jar
> Task :app:compileJava
> Task :app:classes

> Task :app:run
The answer is 42


BUILD SUCCESSFUL in 0s
6 actionable tasks: 6 executed

通过 settings 文件定义复合构建

可以通过使用 Settings.includeBuild(java.lang.Object)settings.gradle(.kts) 文件中声明包含的构建,使上述安排持久化。

settings 文件可以用于同时添加子项目和包含构建。

包含构建按位置添加

settings.gradle.kts
includeBuild("my-utils")

在该示例中,settings.gradle(.kts) 文件组合了原本独立的构建

settings.gradle.kts
rootProject.name = "my-composite"

includeBuild("my-app")
includeBuild("my-utils")
settings.gradle
rootProject.name = 'my-composite'

includeBuild 'my-app'
includeBuild 'my-utils'

要从 my-composite 执行 my-app 构建中的 run 任务,请运行 ./gradlew my-app:app:run

您可以选择在 my-composite 中定义一个依赖于 my-app:app:runrun 任务,以便您可以执行 ./gradlew run

build.gradle.kts
tasks.register("run") {
    dependsOn(gradle.includedBuild("my-app").task(":app:run"))
}
build.gradle
tasks.register('run') {
    dependsOn gradle.includedBuild('my-app').task(':app:run')
}

包含定义 Gradle 插件的构建

包含构建的一个特殊情况是定义 Gradle 插件的构建。

这些构建应使用 settings 文件 pluginManagement {} 块内的 includeBuild 语句包含。

使用此机制,包含的构建还可以贡献一个 settings 插件,该插件可以在 settings 文件本身中应用

settings.gradle.kts
pluginManagement {
    includeBuild("../url-verifier-plugin")
}
settings.gradle
pluginManagement {
    includeBuild '../url-verifier-plugin'
}

包含构建的限制

大多数构建都可以包含在复合构建中,包括其他复合构建。 但有一些限制。

在常规构建中,Gradle 确保每个项目都有唯一的 项目路径 。 这使得项目可识别和可寻址,而不会发生冲突。

在复合构建中,Gradle 会为来自包含构建的每个项目添加额外的限定,以避免项目路径冲突。 用于标识复合构建中项目的完整路径称为 构建树路径 。 它由包含构建的 构建路径 和项目的 项目路径 组成。

默认情况下,构建路径和项目路径从磁盘上的目录名称和结构派生而来。 由于包含构建可以位于磁盘上的任何位置,因此它们的构建路径由包含目录的名称确定。 这有时会导致冲突。

总而言之,包含的构建必须满足以下要求

  • 每个包含构建都必须具有唯一的构建路径。

  • 每个包含构建路径都不得与主构建的任何项目路径冲突。

这些条件保证即使在复合构建中,每个项目都可以被唯一标识。

如果出现冲突,解决冲突的方法是更改包含构建的 构建名称

settings.gradle.kts
includeBuild("some-included-build") {
    name = "other-name"
}

当复合构建包含在另一个复合构建中时,两个构建都具有相同的父级。 换句话说,嵌套的复合构建结构被扁平化。

与复合构建交互

与复合构建交互通常类似于常规多项目构建。 可以执行任务,可以运行测试,并且可以将构建导入到 IDE 中。

执行任务

可以从命令行或 IDE 中执行包含构建中的任务,方式与执行常规多项目构建中的任务相同。 执行任务将导致执行任务依赖项,以及构建来自其他包含构建的依赖项工件所需的那些任务。

您可以使用完全限定路径调用包含构建中的任务,例如,:included-build-name:project-name:taskName。 项目和任务名称可以 缩写

$ ./gradlew :included-build:subproject-a:compileJava
> Task :included-build:subproject-a:compileJava

$ ./gradlew :i-b:sA:cJ
> Task :included-build:subproject-a:compileJava

从命令行排除任务,您需要提供任务的完全限定路径。

包含构建任务会自动执行以生成所需的依赖项工件,或者 包含构建可以声明对来自包含构建的任务的依赖

导入到 IDE

复合构建最有用的功能之一是 IDE 集成。

导入复合构建允许轻松地将来自单独 Gradle 构建的源代码一起开发。 对于每个包含构建,每个子项目都作为 IntelliJ IDEA 模块或 Eclipse 项目包含。 源依赖项已配置,提供跨构建导航和重构。

声明由包含构建替换的依赖项

默认情况下,Gradle 将配置每个包含构建以确定它可以提供的依赖项。 这样做的算法很简单。 Gradle 将检查包含构建中项目的 group 和 name,并将项目依赖项替换为与 ${project.group}:${project.name} 匹配的任何外部依赖项。

默认情况下,不会为主 构建注册替换项。

要使主构建的(子)项目可通过 ${project.group}:${project.name} 寻址,您可以告诉 Gradle 将主构建视为包含构建,方法是自包含它:includeBuild(".")

在某些情况下,Gradle 确定的默认替换项不足或必须针对特定复合构建进行更正。 对于这些情况,可以显式声明包含构建的替换项。

例如,一个名为 anonymous-library 的单项目构建生成一个 Java 实用程序库,但不声明 group 属性的值

build.gradle.kts
plugins {
    java
}
build.gradle
plugins {
    id 'java'
}

当此构建包含在复合构建中时,它将尝试替换依赖模块 undefined:anonymous-libraryundefinedproject.group 的默认值,anonymous-library 是根项目名称)。 显然,这在复合构建中没有用。

要在复合构建中使用未发布的库,您可以显式声明它提供的替换项

settings.gradle.kts
includeBuild("anonymous-library") {
    dependencySubstitution {
        substitute(module("org.sample:number-utils")).using(project(":"))
    }
}
settings.gradle
includeBuild('anonymous-library') {
    dependencySubstitution {
        substitute module('org.sample:number-utils') using project(':')
    }
}

使用此配置,my-app 复合构建会将对 org.sample:number-utils 的任何依赖项替换为对 anonymous-library 的根项目的依赖项。

为配置停用包含构建替换

如果您需要 解析 也作为包含构建一部分提供的模块的已发布版本,则可以在解析的 Configuration 的 ResolutionStrategy 上停用包含构建替换规则。 这是必要的,因为规则在构建中全局应用,并且 Gradle 默认情况下在解析期间不考虑已发布版本。

例如,我们创建一个单独的 publishedRuntimeClasspath 配置,该配置解析为本地构建之一中也存在的模块的已发布版本。 这是通过停用全局依赖项替换规则来完成的

build.gradle.kts
configurations.create("publishedRuntimeClasspath") {
    resolutionStrategy.useGlobalDependencySubstitutionRules = false

    extendsFrom(configurations.runtimeClasspath.get())
    isCanBeConsumed = false
    attributes.attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage.JAVA_RUNTIME))
}
build.gradle
configurations.create('publishedRuntimeClasspath') {
    resolutionStrategy.useGlobalDependencySubstitutionRules = false

    extendsFrom(configurations.runtimeClasspath)
    canBeConsumed = false
    attributes.attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage, Usage.JAVA_RUNTIME))
}

一个用例是比较已发布和本地构建的 JAR 文件。

必须声明包含构建替换的情况

许多构建将自动作为包含构建运行,而无需声明替换项。 以下是一些需要声明替换项的常见情况

  • 当使用 archivesBaseName 属性设置已发布工件的名称时。

  • 当发布 default 以外的配置时。

  • MavenPom.addFilter() 用于发布与项目名称不匹配的工件时。

  • maven-publishivy-publish 插件用于发布且发布坐标与 ${project.group}:${project.name} 不匹配时。

复合构建替换不起作用的情况

即使显式声明了依赖项替换,某些构建在包含在复合构建中时也无法正常运行。 此限制是因为替换的项目依赖项将始终指向目标项目的 default 配置。 任何时候,项目的默认配置指定的工件和依赖项与发布到仓库的内容不匹配时,复合构建都可能表现出不同的行为。

以下是一些已发布的模块元数据可能与项目默认配置不同的情况

  • 当发布 default 以外的配置时。

  • 当使用 maven-publishivy-publish 插件时。

  • POMivy.xml 文件作为发布的一部分进行调整时。

使用这些功能的构建在包含在复合构建中时无法正常运行。

依赖于包含构建中的任务

虽然包含构建彼此隔离且无法声明直接依赖项,但复合构建可以声明对其包含构建的任务依赖项。 可以使用 Gradle.getIncludedBuilds()Gradle.includedBuild(java.lang.String) 访问包含构建,并通过 IncludedBuild.task(java.lang.String) 方法获取任务引用。

使用这些 API,可以声明对特定包含构建中的任务的依赖项

build.gradle.kts
tasks.register("run") {
    dependsOn(gradle.includedBuild("my-app").task(":app:run"))
}
build.gradle
tasks.register('run') {
    dependsOn gradle.includedBuild('my-app').task(':app:run')
}

或者,您可以声明对某些或所有包含构建中具有特定路径的任务的依赖项

build.gradle.kts
tasks.register("publishDeps") {
    dependsOn(gradle.includedBuilds.map { it.task(":publishMavenPublicationToMavenRepository") })
}
build.gradle
tasks.register('publishDeps') {
    dependsOn gradle.includedBuilds*.task(':publishMavenPublicationToMavenRepository')
}

复合构建的局限性

当前实现的局限性包括

  • 不支持发布内容与项目默认配置不一致的包含构建。
    请参阅 复合构建不起作用的情况

  • 当多个复合构建并行运行时,如果多个复合构建包含相同的构建,则可能会发生冲突。
    Gradle 不共享共享复合构建的项目锁,以防止并发执行。