Gradle Build 生命周期中的初始化阶段使用设置文件查找项目根目录中包含的根项目和子项目。

作者 等级 6

然后，对于设置文件中包含的每个项目，Gradle 都会创建一个Project实例。

然后 Gradle 查找相应的构建脚本文件，该文件在配置阶段使用。

构建脚本

每个 Gradle 构建都包含一个或多个项目；根项目和子项目。

项目通常对应于需要构建的软件组件，例如库或应用程序。它可能代表一个库 JAR、一个 Web 应用程序或由其他项目生成的 JAR 组装而成的分发 ZIP。

另一方面，它可能代表要做的事情，例如将应用程序部署到临时或生产环境。

Gradle 脚本使用 Groovy DSL 或 Kotlin DSL（特定领域语言）编写。

构建脚本配置项目并与 类型的对象关联Project。

建造

当构建脚本执行时，它会配置Project.

构建脚本可以是*.gradleGroovy 中的文件，也可以是*.gradle.ktsKotlin 中的文件。

构建脚本配置Project对象及其子对象。

物体Project​

该对象是Gradle APIProject的一部分：

  • 在 Groovy DSL 中，可以在此处Project找到对象文档。

  • 在 Kotlin DSL 中，可以在此处Project找到对象文档。

构建脚本中的许多顶级属性和块都是项目 API 的一部分。

例如，以下构建脚本使用Project.name属性来打印项目的名称：

build.gradle.kts
println(name)
println(project.name)
build.gradle
println name
println project.name
$ gradle -q check
project-api
project-api

两个println语句都打印出相同的属性。

name第一个使用对象属性的顶级引用Project。第二条语句使用project可用于任何构建脚本的属性，该属性返回关联的Project对象。

标准项目属性

该Project对象在构建脚本中公开一组标准属性。

下表列出了一些常用的属性：

姓名 类型 描述

name

String

项目目录的名称。

path

String

项目的完全限定名称。

description

String

项目的描述。

dependencies

DependencyHandler

返回项目的依赖处理程序。

repositories

RepositoryHandler

返回项目的存储库处理程序。

layout

ProjectLayout

提供对项目的几个重要位置的访问。

group

Object

这个项目的小组。

version

Object

该项目的版本。

下表列出了几种常用的方法：

姓名 描述

uri()

将文件路径解析为 URI，相对于该项目的项目目录。

task()

使用给定名称创建一个任务并将其添加到此项目中。

构建脚本结构

{ …​ }Build 脚本由Groovy 和 Kotlin 中的一个特殊对象组成。该对象在 Kotlin 中称为lambda ，在 Groovy 中称为闭包。

简而言之，该plugins{ }块是一个方法调用，其中传递 Kotlin lambda对象或 Groovy闭包对象作为参数。它的缩写形式是：

plugins(function() {
    id("plugin")
})

块映射到 Gradle API 方法。

函数内的代码针对一个对象执行，该对象在 Kotlin lambda 中this称为接收器，在 Groovy 闭包中称为委托。 Gradle 确定正确的this对象并调用正确的相应方法。this方法调用对象的 的类型id("plugin")为PluginDependenciesSpec。

构建脚本本质上是由构建在 DSL 之上的 Gradle API 调用组成。 Gradle 从上到下逐行执行脚本。

让我们看一个例子并将其分解：

build.gradle.kts
plugins {                                                               (1)
    id("org.jetbrains.kotlin.jvm") version "1.9.0"
    id("application")
}

repositories {                                                          (2)
    mavenCentral()
}

dependencies {                                                          (3)
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
    testImplementation("org.junit.jupiter:junit-jupiter-engine:5.9.3")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
    implementation("com.google.guava:guava:32.1.1-jre")
}

application {                                                           (4)
    mainClass = "com.example.Main"
}

tasks.named<Test>("test") {                                             (5)
    useJUnitPlatform()
}
1 Apply plugins to the build.
2 Define the locations where dependencies can be found.
3 Add dependencies.
4 Set properties.
5 Register and configure tasks.
build.gradle
plugins {                                                               (1)
    id 'org.jetbrains.kotlin.jvm' version '1.9.0'
    id 'application'
}

repositories {                                                          (2)
    mavenCentral()
}

dependencies {                                                          (3)
    testImplementation 'org.jetbrains.kotlin:kotlin-test-junit5'
    testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.9.3'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    implementation 'com.google.guava:guava:32.1.1-jre'
}

application {                                                           (4)
    mainClass = 'com.example.Main'
}

tasks.named('test') {                                                   (5)
    useJUnitPlatform()
}
1 Apply plugins to the build.
2 Define the locations where dependencies can be found.
3 Add dependencies.
4 Set properties.
5 Register and configure tasks.

1. 将插件应用到构建中

插件用于扩展 Gradle。它们还用于模块化和重用项目配置。

可以使用插件脚本块应用插件PluginDependenciesSpec。

插件块是首选：

plugins {
    id("org.jetbrains.kotlin.jvm") version "1.9.0"
    id("application")
}

在示例中，application已应用 Gradle 附带的插件，将我们的项目描述为 Java 应用程序。

Kotlin gradle 插件 1.9.0 版本也已应用。该插件不包含在 Gradle 中，因此必须使用 aplugin id和 a进行描述plugin version，以便 Gradle 可以找到并应用它。

2.定义可以找到依赖的位置

一个项目通常具有完成其工作所需的许多依赖项。依赖项包括 Gradle 必须下载才能成功构建的插件、库或组件。

构建脚本让 Gradle 知道在哪里查找依赖项的二进制文件。可以提供多个位置：

repositories {
    mavenCentral()
    google()
}

在示例中，将从Maven Central Repository下载guava库和 JetBrains Kotlin 插件 ( ) 。org.jetbrains.kotlin.jvm

3.添加依赖

一个项目通常具有完成其工作所需的许多依赖项。这些依赖项通常是在项目源代码中导入的预编译类的库。

依赖项通过配置进行管理并从存储库中检索。

使用DependencyHandlerbyProject.getDependencies()方法返回的值来管理依赖关系。使用RepositoryHandlerbyProject.getRepositories()方法返回来管理存储库。

dependencies {
    implementation("com.google.guava:guava:32.1.1-jre")
}

在示例中，应用程序代码使用 Google 的guava库。 Guava 提供了用于集合、缓存、原语支持、并发、通用注释、字符串处理、I/O 和验证的实用方法。

4. 设置属性

插件可以使用扩展向项目添加属性和方法。

该Project对象有一个关联ExtensionContainer对象，其中包含已应用于项目的插件的所有设置和属性。

在示例中，application插件添加了一个application属性，用于详细说明 Java 应用程序的主类：

application {
    mainClass = "com.example.Main"
}

5. 注册并配置任务

任务执行一些基本工作，例如编译类、运行单元测试或压缩 WAR 文件。

虽然任务通常在插件中定义，但您可能需要在构建脚本中注册或配置任务。

注册任务会将任务添加到您的项目中。

您可以使用以下方法在项目中注册任务TaskContainer.register(java.lang.String)：

tasks.register<Zip>("zip-reports") {
    from 'Reports/'
    include '*'
    archiveName 'Reports.zip'
    destinationDir(file('/dir'))
}

您可能已经看到了应该避免的TaskContainer.create(java.lang.String)方法的用法：

tasks.create<Zip>("zip-reports") {
    from 'Reports/'
    include '*'
    archiveName 'Reports.zip'
    destinationDir(file('/dir'))
}
register()，它可以避免任务配置，优于create().

您可以使用以下方法找到任务并对其进行配置TaskCollection.named(java.lang.String)：

tasks.named<Test>("test") {
    useJUnitPlatform()
}

下面的示例将Javadoc任务配置为从 Java 代码自动生成 HTML 文档：

tasks.named("javadoc").configure {
    exclude 'app/Internal*.java'
    exclude 'app/internal/*'
    exclude 'app/internal/*'
}

构建脚本

构建脚本由零个或多个语句和脚本块组成：

println(project.layout.projectDirectory);

语句可以包括方法调用、属性分配和局部变量定义：

version = '1.0.0.GA'

脚本块是一个方法调用，它采用闭包/lambda 作为参数：

configurations {
}

闭包/lambda 在执行时配置一些委托对象：

repositories {
    google()
}

构建脚本也是 Groovy 或 Kotlin 脚本：

build.gradle.kts
tasks.register("upper") {
    doLast {
        val someString = "mY_nAmE"
        println("Original: $someString")
        println("Upper case: ${someString.toUpperCase()}")
    }
}
build.gradle
tasks.register('upper') {
    doLast {
        String someString = 'mY_nAmE'
        println "Original: $someString"
        println "Upper case: ${someString.toUpperCase()}"
    }
}
$ gradle -q upper
Original: mY_nAmE
Upper case: MY_NAME

它可以包含 Groovy 或 Kotlin 脚本中允许的元素，例如方法定义和类定义：

build.gradle.kts
tasks.register("count") {
    doLast {
        repeat(4) { print("$it ") }
    }
}
build.gradle
tasks.register('count') {
    doLast {
        4.times { print "$it " }
    }
}
$ gradle -q count
0 1 2 3

灵活的任务注册

使用 Groovy 或 Kotlin 语言的功能，您可以在循环中注册多个任务：

build.gradle.kts
repeat(4) { counter ->
    tasks.register("task$counter") {
        doLast {
            println("I'm task number $counter")
        }
    }
}
build.gradle
4.times { counter ->
    tasks.register("task$counter") {
        doLast {
            println "I'm task number $counter"
        }
    }
}
$ gradle -q task1
I'm task number 1

声明变量

构建脚本可以声明两个变量：局部变量和额外属性。

局部变量

使用关键字声明局部变量val。局部变量仅在声明它们的范围内可见。它们是底层 Kotlin 语言的一个功能。

使用关键字声明局部变量def。局部变量仅在声明它们的范围内可见。它们是底层 Groovy 语言的一个功能。

build.gradle.kts
val dest = "dest"

tasks.register<Copy>("copy") {
    from("source")
    into(dest)
}
build.gradle
def dest = 'dest'

tasks.register('copy', Copy) {
    from 'source'
    into dest
}

额外属性

Gradle 的增强对象（包括项目、任务和源集）可以保存用户定义的属性。

通过所属对象的属性添加、读取和设置额外的属性extra。或者，您可以使用 .kotlin 委托属性来访问额外的属性by extra。

通过所属对象的属性添加、读取和设置额外的属性ext。或者，您可以使用ext块同时添加多个属性。

build.gradle.kts
plugins {
    id("java-library")
}

val springVersion by extra("3.1.0.RELEASE")
val emailNotification by extra { "build@master.org" }

sourceSets.all { extra["purpose"] = null }

sourceSets {
    main {
        extra["purpose"] = "production"
    }
    test {
        extra["purpose"] = "test"
    }
    create("plugin") {
        extra["purpose"] = "production"
    }
}

tasks.register("printProperties") {
    val springVersion = springVersion
    val emailNotification = emailNotification
    val productionSourceSets = provider {
        sourceSets.matching { it.extra["purpose"] == "production" }.map { it.name }
    }
    doLast {
        println(springVersion)
        println(emailNotification)
        productionSourceSets.get().forEach { println(it) }
    }
}
build.gradle
plugins {
    id 'java-library'
}

ext {
    springVersion = "3.1.0.RELEASE"
    emailNotification = "build@master.org"
}

sourceSets.all { ext.purpose = null }

sourceSets {
    main {
        purpose = "production"
    }
    test {
        purpose = "test"
    }
    plugin {
        purpose = "production"
    }
}

tasks.register('printProperties') {
    def springVersion = springVersion
    def emailNotification = emailNotification
    def productionSourceSets = provider {
        sourceSets.matching { it.purpose == "production" }.collect { it.name }
    }
    doLast {
        println springVersion
        println emailNotification
        productionSourceSets.get().each { println it }
    }
}
$ gradle -q printProperties
3.1.0.RELEASE
build@master.org
main
plugin

project此示例通过 向对象添加两个额外的属性by extra。此外，此示例purpose通过设置extra["purpose"]为为每个源集添加一个名为 的属性null。添加后，您可以通过读取和设置这些属性extra。

project此示例通过块向对象添加两个额外属性ext。此外，此示例purpose通过设置ext.purpose为为每个源集添加一个名为 的属性null。添加后，您可以像预定义的属性一样读取和设置所有这些属性。

Gradle 需要特殊的语法来添加属性，以便它可以快速失败。例如，这允许 Gradle 识别脚本何时尝试设置不存在的属性。您可以在任何可以访问其所属对象的地方访问额外的属性。这为额外属性提供了比局部变量更广泛的范围。子项目可以访问其父项目的额外属性。

有关额外属性的更多信息，请参阅 API 文档中的ExtraPropertiesExtension 。

配置任意对象

示例greet()任务显示了任意对象配置的示例：

build.gradle.kts
class UserInfo(
    var name: String? = null, 
    var email: String? = null
)

tasks.register("configure") {
    val user = UserInfo().apply {
        name = "Isaac Newton"
        email = "isaac@newton.me"
    }
    doLast {
        println(user.name)
        println(user.email)
    }
}
build.gradle
class UserInfo {
    String name
    String email
}

tasks.register('configure') {
    def user = configure(new UserInfo()) {
        name = "Isaac Newton"
        email = "isaac@newton.me"
    }
    doLast {
        println user.name
        println user.email
    }
}
$ gradle -q greet
Isaac Newton
isaac@newton.me

闭幕代表

每个闭包都有一个delegate对象。 Groovy 使用此委托来查找对非局部变量和闭包参数的变量和方法引用。 Gradle 将其用于配置闭包，其中delegate对象指的是正在配置的对象。

build.gradle
dependencies {
    assert delegate == project.dependencies
    testImplementation('junit:junit:4.13')
    delegate.testImplementation('junit:junit:4.13')
}

默认导入

为了使构建脚本更加简洁，Gradle 会自动向脚本添加一组 import 语句。

因此，throw new org.gradle.api.tasks.StopExecutionException()您可以不写throw new StopExecutionException()而是写。

Gradle 隐式地将以下导入添加到每个脚本中：

Gradle 默认导入
import org.gradle.*
import org.gradle.api.*
import org.gradle.api.artifacts.*
import org.gradle.api.artifacts.component.*
import org.gradle.api.artifacts.dsl.*
import org.gradle.api.artifacts.ivy.*
import org.gradle.api.artifacts.maven.*
import org.gradle.api.artifacts.query.*
import org.gradle.api.artifacts.repositories.*
import org.gradle.api.artifacts.result.*
import org.gradle.api.artifacts.transform.*
import org.gradle.api.artifacts.type.*
import org.gradle.api.artifacts.verification.*
import org.gradle.api.attributes.*
import org.gradle.api.attributes.java.*
import org.gradle.api.attributes.plugin.*
import org.gradle.api.cache.*
import org.gradle.api.capabilities.*
import org.gradle.api.component.*
import org.gradle.api.configuration.*
import org.gradle.api.credentials.*
import org.gradle.api.distribution.*
import org.gradle.api.distribution.plugins.*
import org.gradle.api.execution.*
import org.gradle.api.file.*
import org.gradle.api.flow.*
import org.gradle.api.initialization.*
import org.gradle.api.initialization.definition.*
import org.gradle.api.initialization.dsl.*
import org.gradle.api.initialization.resolve.*
import org.gradle.api.invocation.*
import org.gradle.api.java.archives.*
import org.gradle.api.jvm.*
import org.gradle.api.launcher.cli.*
import org.gradle.api.logging.*
import org.gradle.api.logging.configuration.*
import org.gradle.api.model.*
import org.gradle.api.plugins.*
import org.gradle.api.plugins.antlr.*
import org.gradle.api.plugins.catalog.*
import org.gradle.api.plugins.jvm.*
import org.gradle.api.plugins.quality.*
import org.gradle.api.plugins.scala.*
import org.gradle.api.problems.*
import org.gradle.api.provider.*
import org.gradle.api.publish.*
import org.gradle.api.publish.ivy.*
import org.gradle.api.publish.ivy.plugins.*
import org.gradle.api.publish.ivy.tasks.*
import org.gradle.api.publish.maven.*
import org.gradle.api.publish.maven.plugins.*
import org.gradle.api.publish.maven.tasks.*
import org.gradle.api.publish.plugins.*
import org.gradle.api.publish.tasks.*
import org.gradle.api.reflect.*
import org.gradle.api.reporting.*
import org.gradle.api.reporting.components.*
import org.gradle.api.reporting.dependencies.*
import org.gradle.api.reporting.dependents.*
import org.gradle.api.reporting.model.*
import org.gradle.api.reporting.plugins.*
import org.gradle.api.resources.*
import org.gradle.api.services.*
import org.gradle.api.specs.*
import org.gradle.api.tasks.*
import org.gradle.api.tasks.ant.*
import org.gradle.api.tasks.application.*
import org.gradle.api.tasks.bundling.*
import org.gradle.api.tasks.compile.*
import org.gradle.api.tasks.diagnostics.*
import org.gradle.api.tasks.diagnostics.configurations.*
import org.gradle.api.tasks.incremental.*
import org.gradle.api.tasks.javadoc.*
import org.gradle.api.tasks.options.*
import org.gradle.api.tasks.scala.*
import org.gradle.api.tasks.testing.*
import org.gradle.api.tasks.testing.junit.*
import org.gradle.api.tasks.testing.junitplatform.*
import org.gradle.api.tasks.testing.testng.*
import org.gradle.api.tasks.util.*
import org.gradle.api.tasks.wrapper.*
import org.gradle.api.toolchain.management.*
import org.gradle.authentication.*
import org.gradle.authentication.aws.*
import org.gradle.authentication.http.*
import org.gradle.build.event.*
import org.gradle.buildinit.*
import org.gradle.buildinit.plugins.*
import org.gradle.buildinit.tasks.*
import org.gradle.caching.*
import org.gradle.caching.configuration.*
import org.gradle.caching.http.*
import org.gradle.caching.local.*
import org.gradle.concurrent.*
import org.gradle.external.javadoc.*
import org.gradle.ide.visualstudio.*
import org.gradle.ide.visualstudio.plugins.*
import org.gradle.ide.visualstudio.tasks.*
import org.gradle.ide.xcode.*
import org.gradle.ide.xcode.plugins.*
import org.gradle.ide.xcode.tasks.*
import org.gradle.ivy.*
import org.gradle.jvm.*
import org.gradle.jvm.application.scripts.*
import org.gradle.jvm.application.tasks.*
import org.gradle.jvm.tasks.*
import org.gradle.jvm.toolchain.*
import org.gradle.language.*
import org.gradle.language.assembler.*
import org.gradle.language.assembler.plugins.*
import org.gradle.language.assembler.tasks.*
import org.gradle.language.base.*
import org.gradle.language.base.artifact.*
import org.gradle.language.base.compile.*
import org.gradle.language.base.plugins.*
import org.gradle.language.base.sources.*
import org.gradle.language.c.*
import org.gradle.language.c.plugins.*
import org.gradle.language.c.tasks.*
import org.gradle.language.cpp.*
import org.gradle.language.cpp.plugins.*
import org.gradle.language.cpp.tasks.*
import org.gradle.language.java.artifact.*
import org.gradle.language.jvm.tasks.*
import org.gradle.language.nativeplatform.*
import org.gradle.language.nativeplatform.tasks.*
import org.gradle.language.objectivec.*
import org.gradle.language.objectivec.plugins.*
import org.gradle.language.objectivec.tasks.*
import org.gradle.language.objectivecpp.*
import org.gradle.language.objectivecpp.plugins.*
import org.gradle.language.objectivecpp.tasks.*
import org.gradle.language.plugins.*
import org.gradle.language.rc.*
import org.gradle.language.rc.plugins.*
import org.gradle.language.rc.tasks.*
import org.gradle.language.scala.tasks.*
import org.gradle.language.swift.*
import org.gradle.language.swift.plugins.*
import org.gradle.language.swift.tasks.*
import org.gradle.maven.*
import org.gradle.model.*
import org.gradle.nativeplatform.*
import org.gradle.nativeplatform.platform.*
import org.gradle.nativeplatform.plugins.*
import org.gradle.nativeplatform.tasks.*
import org.gradle.nativeplatform.test.*
import org.gradle.nativeplatform.test.cpp.*
import org.gradle.nativeplatform.test.cpp.plugins.*
import org.gradle.nativeplatform.test.cunit.*
import org.gradle.nativeplatform.test.cunit.plugins.*
import org.gradle.nativeplatform.test.cunit.tasks.*
import org.gradle.nativeplatform.test.googletest.*
import org.gradle.nativeplatform.test.googletest.plugins.*
import org.gradle.nativeplatform.test.plugins.*
import org.gradle.nativeplatform.test.tasks.*
import org.gradle.nativeplatform.test.xctest.*
import org.gradle.nativeplatform.test.xctest.plugins.*
import org.gradle.nativeplatform.test.xctest.tasks.*
import org.gradle.nativeplatform.toolchain.*
import org.gradle.nativeplatform.toolchain.plugins.*
import org.gradle.normalization.*
import org.gradle.platform.*
import org.gradle.platform.base.*
import org.gradle.platform.base.binary.*
import org.gradle.platform.base.component.*
import org.gradle.platform.base.plugins.*
import org.gradle.plugin.devel.*
import org.gradle.plugin.devel.plugins.*
import org.gradle.plugin.devel.tasks.*
import org.gradle.plugin.management.*
import org.gradle.plugin.use.*
import org.gradle.plugins.ear.*
import org.gradle.plugins.ear.descriptor.*
import org.gradle.plugins.ide.*
import org.gradle.plugins.ide.api.*
import org.gradle.plugins.ide.eclipse.*
import org.gradle.plugins.ide.idea.*
import org.gradle.plugins.signing.*
import org.gradle.plugins.signing.signatory.*
import org.gradle.plugins.signing.signatory.pgp.*
import org.gradle.plugins.signing.type.*
import org.gradle.plugins.signing.type.pgp.*
import org.gradle.process.*
import org.gradle.swiftpm.*
import org.gradle.swiftpm.plugins.*
import org.gradle.swiftpm.tasks.*
import org.gradle.testing.base.*
import org.gradle.testing.base.plugins.*
import org.gradle.testing.jacoco.plugins.*
import org.gradle.testing.jacoco.tasks.*
import org.gradle.testing.jacoco.tasks.rules.*
import org.gradle.testkit.runner.*
import org.gradle.util.*
import org.gradle.vcs.*
import org.gradle.vcs.git.*
import org.gradle.work.*
import org.gradle.workers.*

下一步： 了解如何使用任务>>