第五十五章. 构建的生命周期

Gradle 构建有三个不同的阶段。
A Gradle build has three distinct phases.

在构建脚本文件旁边，Gradle 定义了一个设置文件。这个设置文件是 Gradle 通过命名约定来决定的，它的默认名称是 settings.gradle。在本章中，稍后我们会解释 Gradle 是如何查找设置文件的。
Beside the build script files, Gradle defines a settings file. The settings file is determined by Gradle via a naming convention. The default name for this file is settings.gradle. Later in this chapter we explain how Gradle looks for a settings file.

这个设置文件会在初始化阶段执行。多项目构建必须在这个多项目的层次结构的根项目下有一个 settings.gradle 文件。这个文件是必不可少的，因为在这个设置文件中，定义了哪些项目会加处多项目构建（见《第五十六章，多项目构建》）。对于单项目构建，有没有设置文件都可以。例如，你可能需要它将一些库添加到构建脚本类路径中（见《第五十九章，组织构建逻辑》）。我们先来看一个单项目的构建：
The settings file gets executed during the initialization phase. A multiproject build must have a settings.gradle file in the root project of the multiproject hierarchy. It is required because in the settings file it is defined, which projects are taking part in the multi-project build (see Chapter 56, Multi-project Builds). For a single-project build, a settings file is optional. You might need it for example, to add libraries to your build script classpath (see Chapter 59, Organizing Build Logic). Let's first do some introspection with a single project build:

println 'This is executed during the initialization phase.'

println 'This is executed during the configuration phase.'

task configured {
    println 'This is also executed during the configuration phase.'
}

task test << {
    println 'This is executed during the execution phase.'
}

> gradle test
This is executed during the initialization phase.
This is executed during the configuration phase.
This is also executed during the configuration phase.
:test
This is executed during the execution phase.

BUILD SUCCESSFUL

Total time: 1 secs

对于一个构建脚本，属性访问和方法调用会委托给一个项目对象。同样，设置文件中的属性访问和方法调用也会委派给设置对象。可以看一下 Settings。
For a build script, the property access and method calls are delegated to a project object. Similarly property access and method calls within the settings file is delegated to a settings object. Have a look at Settings.

多项目构建是指在一个 Gradle 执行中构建多个项目的构建。你必须在设置文件中声明参与多项目构建的项目。关于多项目构建，在专门讨论这一主题的章节中还有更多的介绍（参见《第五十六章，多项目构建》）。
A multi-project build is a build where you build more than one project during a single execution of Gradle. You have to declare the projects taking part in the multiproject build in the settings file. There is much more to say about multi-project builds in the chapter dedicated to this topic (see Chapter 56, Multi-project Builds).

include 'project1', 'project2:child', 'project3:child1'

includeFlat 'project3', 'project4'

println rootProject.name
println project(':projectA').name

rootProject.name = 'main'
project(':projectA').projectDir = new File(settingsDir, '../my-project-a')
project(':projectA').buildFileName = 'projectA.gradle'

Gradle 是怎么知道要构建单个或多项目呢？如果你在一个有设置文件的目录中触发多项目构建，那么情况很简单。但 Gradle 也允许你在参与构建的任意子项目中执行构建。^[20] 如果你在没有 settings.gradle 文件的项目中执行 Gradle，Gradle 将执行以下操作：
How does Gradle know whether to do a single or multiproject build? If you trigger a multiproject build from the directory where the settings file is, things are easy. But Gradle also allows you to execute the build from within any subproject taking part in the build. ^[20] If you execute Gradle from within a project that has no settings.gradle file, Gradle does the following:

这种行为的目的是什么？无论你进入的项目是否为多项目构建的子项目，Gradle 都必须查明该项目是否为多项目构建的子项目。当然，如果它是子项目，那么就只构建子项目及其依赖的项目。但是 Gradle 需要为整个多项目构建创建构建配置（请参阅《第五十六章，多项目构建》）。通过 -u 命令行选项，你可以告诉 Gradle 不要在父层次结构中查找 settings.gradle 文件。然后，当前项目将始终作为单项目进行构建。如果当前项目包含了 settings.gradle 文件，那么 -u 选项将没有意义。这样的构建始终这样执行：
What is the purpose of this behavior? Somehow Gradle has to find out, whether the project you are into, is a subproject of a multiproject build or not. Of course, if it is a subproject, only the subproject and its dependent projects are build. But Gradle needs to create the build configuration for the whole multiproject build (see Chapter 56, Multi-project Builds). Via the -u command line option, you can tell Gradle not to look in the parent hierarchy for a settings.gradle file. The current project is then always build as a single project build. If the current project contains a settings.gradle file, the -u option has no meaning. Such a build is always executed as:

自动搜索设置文件只适用于具有物理上的层次结构或平面布局的多项目构建。对于平面布局，你还必须遵循上面所述的命名约定。Gradle 支持多项目构建的任意物理布局。但是，对于这种任意布局，你需要从设置文件所在的目录执行构建。有关如何从根目录运行部分构建，请参阅《第56.4节，使用任务的绝对路径运行任务）。在下个发行版中，我们希望通过在命令行参数中指定设置文件的路径，来从子项目中启用部分构建。Gradle 为参与构建的每个项目创建项目对象。对于单项目构建而言，它是一个项目对象。而对于多项目构建，它们是 Settings 对象指定的所有项目对象（加上根项目对象）。默认情况下，每个项目对象的名称是其顶级目录的名称。除根项目之外，每个项目都有父项目，并且可能还有子项目。
The auto search for a settings file does only work for multi-project builds with a physical hierarchical or flat layout. For a flat layout you must additionally obey to the naming convention described above. Gradle supports arbitrary physical layouts for a multiproject build. But for such arbitrary layouts you need to execute the build from the directory where the settings file is located. For how to run partial builds from the root see Section 56.4, “Running tasks by their absolute path”. In our next release we want to enable partial builds from subprojects by specifying the location of the settings file as a command line parameter. Gradle creates Project objects for every project taking part in the build. For a single project build this is only one project. For a multi-project build these are the projects specified in Settings object (plus the root project). Each project object has by default a name equals to the name of its top level directory. Every project except the root project has a parent project and might have child projects.

对于单项目构建， 初始化后 阶段的工作流程相当简单。构建脚本会针对初始化阶段期间创建的项目对象执行。然后 Gradle 会查找与作为命令行参数传进来的名称相同的任务名。如果这些任务名存在，那么会按参数的顺序将这些任务作为单独的构建执行。关于多项目构建的配置与执行，在《第五十六章，多项目构建》中有论述。
For a single project build, the workflow of the after initialization phases are pretty simple. The build script is executed against the project object that was created during the initialization phase. Then Gradle looks for tasks with names equal to those passed as command line arguments. If these task names exist, they are executed as a separate build in the order you have passed them. The configuration and execution for multi-project builds is discussed in Chapter 56, Multi-project Builds.

构建脚本可以在构建过程通过其生命周期时接收通知。这些通知通常采用两种形式：你可以实现一个特定的监听器接口，或提供一个用于在触发通知时执行的闭包。以下是使用闭包的例子。有关如何使用监听器接口的详细信息，请参阅 API 文档。
Your build script can receive notifications as the build progresses through its lifecycle. These notifications generally take 2 forms: You can either implement a particular listener interface, or you can provide a closure to execute when the notification is fired. The examples below use closures. For details on how to use the listener interfaces, refer to the API documentation.

allprojects {
    afterEvaluate { project ->
        if (project.hasTests) {
            println "Adding test task to $project"
            project.task('test') << {
                println "Running tests for $project"
            }
        }
    }
}

hasTests = true

> gradle -q test
Adding test task to project ':projectA'
Running tests for project ':projectA'

gradle.afterProject {project, projectState ->
    if (projectState.failure) {
        println "Evaluation of $project FAILED"
    } else {
        println "Evaluation of $project succeeded"
    }
}

> gradle -q test
Evaluation of root project 'buildProjectEvaluateEvents' succeeded
Evaluation of project ':projectA' succeeded
Evaluation of project ':projectB' FAILED

tasks.whenTaskAdded { task ->
    task.ext.srcDir = 'src/main/java'
}

task a

println "source dir is $a.srcDir"

> gradle -q a
source dir is src/main/java

task ok

task broken(dependsOn: ok) << {
    throw new RuntimeException('broken')
}

gradle.taskGraph.beforeTask { Task task ->
    println "executing $task ..."
}

gradle.taskGraph.afterTask { Task task, TaskState state ->
    if (state.failure) {
        println "FAILED"
    }
    else {
        println "done"
    }
}

> gradle -q broken
executing task ':ok' ...
done
executing task ':broken' ...
FAILED