第56章 ビルドのライフサイクル

A Gradle build has three distinct phases.

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.

ビルドスクリプトの他、Gradleではビルドの「設定ファイル」を作成することができます。設定ファイルの場所はGradleの規約により決定され、デフォルトではプロジェクトディレクトリのsettings.gradleです。この設定ファイルをGradleがどのように探すのかについては、後ほど解説します。

The settings file is 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 the settings file defines which projects are taking part in the multi-project build (see 57章マルチプロジェクトのビルド). For a single-project build, a settings file is optional. Besides defining the included projects, you might need it to add libraries to your build script classpath (see 60章ビルドロジックの体系化). Let's first do some introspection with a single project build:

設定ファイルは、初期化フェーズで使用されます。マルチプロジェクトの場合、settings.gradleファイルは必須です。ルートとなるプロジェクトに必ず配置しなければなりません。この設定ファイルにより、どのプロジェクトがビルドに参加するか決定するからです(57章マルチプロジェクトのビルド参照)。シングルプロジェクトの場合は設定ファイルはなくてもかまいません。ビルドスクリプトのクラスパスにライブラリを追加するときなどはこの設定ファイルを使うこともあるでしょう(60章ビルドロジックの体系化参照)。設定ファイルの読み込み、フェーズ実行の内部動作を、シングルプロジェクトの例を使って見てみます。

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.'
}

task testBoth {
    doFirst {
      println 'This is executed first during the execution phase.'
    }
    doLast {
      println 'This is executed last during the execution phase.'
    }
    println 'This is executed during the configuration phase as well.'
}

> gradle test testBoth
This is executed during the initialization phase.
This is executed during the configuration phase.
This is also executed during the configuration phase.
This is executed during the configuration phase as well.
:test
This is executed during the execution phase.
:testBoth
This is executed first during the execution phase.
This is executed last during the execution phase.

BUILD SUCCESSFUL

Total time: 1 secs

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. Look at Settings class in the API documentation for more information.

ビルドスクリプト内でのプロパティアクセスやメソッド呼び出しは、Projectインスタンスに委譲されますが、それと同様に設定ファイル内でのプロパティアクセス、メソッド呼び出しはsettingsインスタンスに委譲されます。Settingsをご参照ください。

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 57章マルチプロジェクトのビルド).

マルチプロジェクトとは、ある一つのプロジェクトをビルドしているときに、関連する別のプロジェクトも呼び出されてビルドされるよう構成されたプロジェクトの集まりです。マルチプロジェクトのビルドにプロジェクトを参加させるには、設定ファイルでそのことを宣言しなくてはなりません。マルチプロジェクトについては、専用の章をもうけて詳しく説明します(57章マルチプロジェクトのビルド参照)。

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'

How does Gradle know whether to do a single or multiproject build? If you trigger a multiproject build from a directory with a settings file is, things are easy. But Gradle also allows you to execute the build from within any subproject taking part in the build. ^[30] If you execute Gradle from within a project with no settings.gradle file, Gradle looks for a settings.gradle file in the following way:

Gradleは、現在ビルドしているものがマルチプロジェクトかシングルプロジェクトか、どうやって知るのでしょう。マルチプロジェクトのビルドを、設定ファイルのあるディレクトリから起動しているなら話は簡単ですが、Gradleはサブプロジェクトのディレクトリからビルドを実行することもできるようになっています。 ^[31] Gradleは、settings.gradleのないディレクトリで実行された場合、以下のように動作します。

What is the purpose of this behavior? Gradle needs to determine whether the project you are in is a subproject of a multiproject build or not. Of course, if it is a subproject, only the subproject and its dependent projects are built, but Gradle needs to create the build configuration for the whole multiproject build (see 57章マルチプロジェクトのビルド). You can use the -u command line option to tell Gradle not to look in the parent hierarchy for a settings.gradle file. The current project is then always built 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は、それを何とか決定しなくてはなりません。サブプロジェクトだった場合、Gradleはプロジェクト・ツリー全体の設定情報を作成する必要があるからです。ビルド対象がそのサブプロジェクトのみだったとしてもです(57章マルチプロジェクトのビルド参照)。-uオプションをつけてGradleを実行すれば、親階層をたどってsettings.gradleを探しに行くことはありません。つまり、(settings.gradleのない)現在ビルドしているプロジェクトは、常にシングルプロジェクトだと認識されるわけです。現在のプロジェクトにsettings.gradleがある場合は、-uをつけても意味はありません。settings.gradleをもつプロジェクトは以下のように処理されます。

The automatic search for a settings.gradle file only works for multi-project builds with a physical hierarchical or flat layout. For a flat layout you must additionally follow the naming convention described above (“master”). 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 information on how to run partial builds from the root see 「絶対パスによるタスクの実行Running tasks by their absolute path」.

この設定ファイルの探索処理は、プロジェクトのディレクトリ構造が前述した階層レイアウトとフラットレイアウトのどちらかであることを想定したものです。さらに、フラットなレイアウトを採用した場合は、前述したような命名規約(settings.gradleをmasterディレクトリに配置する)に従う必要があります。マルチプロジェクト・ツリーはどんなディレクトリ構造からでも構築できますが、その場合は設定ファイルがあるディレクトリでGradleを実行しなければなりません。ルートプロジェクトからでも、一部のプロジェクトのみビルドすることは可能です。「絶対パスによるタスクの実行Running tasks by their absolute path」をご参照ください。次のリリースでは、コマンドラインから設定ファイルの場所を指定してやることで、サブプロジェクトからの部分ビルドをサポートする予定です。

初期化フェーズでは、ビルドに参加しているすべてのプロジェクトについてProjectオブジェクトが作成されます。シングルプロジェクトの場合はひとつだけ作成され、マルチプロジェクトの場合はSettingsオブジェクトで指定されているすべてのプロジェクトと、ルートプロジェクトのProjectオブジェクトが作成されるのです。作成されたProjectオブジェクトはそれぞれ名前を持っています。デフォルトではプロジェクトのディレクトリ名です。また、ルートプロジェクトをのぞく全てのプロジェクトは親プロジェクトを持っていますし、場合によっては子プロジェクトも設定されているかもしれません。

Gradle creates a Project object for every project taking part in the build. For a multi-project build these are the projects specified in the Settings object (plus the root project). Each project object has by default a name equal to the name of its top level directory, and every project except the root project has a parent project. Any project may have child projects.

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 57章マルチプロジェクトのビルド.

シングルプロジェクトの場合、初期化フェーズ完了後の処理の流れは非常にシンプルです。まず、初期化フェーズで作成されたプロジェクトのビルドスクリプトが実行されます。それから、Gradleはコマンドライン引数に渡されたタスクを探し、見つかればコマンドライン引数の順に別々に実行されます。マルチプロジェクトにおける設定と実行については、57章マルチプロジェクトのビルドを参照してください。

Your build script can receive notifications as the build progresses through its lifecycle. These notifications generally take two 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.

ビルドスクリプト内では、ビルドがそのライフサイクルに従って進行していくなかで、さまざまな通知を受けとって処理できます。この通知を受けとるには大きく分けて二つの方法があります。ひとつは、特定のリスナーインターフェースを実装する方法、もうひとつは通知を受け取ったときに実行されるクロージャを作成する方法です。ここでは、クロージャを使用する方法について例を見ていきたいと思います。リスナーインターフェースを実装する方法についてはAPIドキュメントをご参照ください。

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