This user guide, like Gradle itself, is under very active development. Some parts of Gradle aren't documented as completely as they need to be. Some of the content presented won't be entirely clear or will assume that you know more about Gradle than you do. We need your help to improve this user guide. You can find out more about contributing to the documentation at the Gradle web site.

このユーザーガイドは、Gradle同様、現在活発に更新されているところです。まだGradleについて必要な部分がすべてドキュメント化されているわけではありません。 また、記載内容には明確でない部分やGradleについて読者が知っている以上の知識を要求する部分があるかもしれません。 このガイドを改良していくため、力を貸してください。 ドキュメンテーションへ参加、貢献していただける方はGradleのウェブサイトをご参照ください。

Throughout the user guide, you will find some diagrams that represent dependency relationships between Gradle tasks. These use something analogous to the UML dependency notation, which renders an arrow from one task to the task that the first task depends on.

Here is a list of some of Gradle's features.

Gradleの特長は以下の通りです。

We think the advantages of an internal DSL (based on a dynamic language) over XML are tremendous when used in build scripts. There are a couple of dynamic languages out there. Why Groovy? The answer lies in the context Gradle is operating in. Although Gradle is a general purpose build tool at its core, its main focus are Java projects. In such projects the team members will be very familiar with Java. We think a build should be as transparent as possible to all team members.

ビルドスクリプトを記述するということを考えたとき、XMLに対する内部DSL(動的言語ベース)のアドバンテージというのは途方もなく大きいものです。 ただ、動的な言語はいくつかあるのに、なぜGroovyなのでしょうか。 その答えは、Gradleが想定しているシチュエーション、環境にあります。 Gradleは本質的に言えば一般的な利用が可能な汎用のビルドツールですが、メインとしてフォーカスしているのはJavaのプロジェクトです。 そのようなプロジェクトの場合、チームのメンバーがJavaに習熟しているのは明らかでしょう。 私たちは、ビルドはすべてのチームメンバーに対してできるだけ分かりやすいものであるべきだと考えています。

In that case, you might argue why we don't just use Java as the language for build scripts. We think this is a valid question. It would have the highest transparency for your team and the lowest learning curve, but because of the limitations of Java, such a build language would not be as nice, expressive and powerful as it could be. ^[1] Languages like Python, Groovy or Ruby do a much better job here. We have chosen Groovy as it offers by far the greatest transparency for Java people. Its base syntax is the same as Java's as well as its type system, its package structure and other things. Groovy provides much more on top of that, but with the common foundation of Java.

それならGroovyでなくJavaを使えばいいのにと思われるかもしれません。それはもっともな疑問です。 ビルド用の言語にJavaを使えば、開発チームにとって最高に分かりやすく、学習曲線が最小限緩やかなビルドとなるでしょう。 しかし、Javaはビルド用の言語として使うには表現力や機能に限界があるのです。 ^[2] このような用途には、PythonやGroovy、Rubyのような言語の方が向いています。 私たちは、Java世界の住人にとって断然飛び抜けた分かりやすさを提供するGroovyを選択しました。 Groovyの文法は、型システム、パッケージ構造、その他諸々についてJavaをベースにしています。Groovyはその上に様々な機能を構築していますが、土台はJavaと同じなのです。

For Java developers with Python or Ruby knowledge or the desire to learn them, the above arguments don't apply. The Gradle design is well-suited for creating another build script engine in JRuby or Jython. It just doesn't have the highest priority for us at the moment. We happily support any community effort to create additional build script engines.

Javaの開発者であっても、PythonやRubyの知識を持っていたり、それらを楽しく学んでいるのなら上記の議論は当てはまりません。 Gradleはビルドスクリプト・エンジンとしてJRubyやJythonを使えるよう適切にデザインされています。 私達にとって、目下のところはそれらの優先度は高くありませんが。 私たちは、そういった追加のビルドスクリプトエンジンを作っていただけるあらゆるコミュニティを喜んでサポートします。

The following tutorials introduce some of the basics of Gradle, to help you get started.

次のチュートリアルはGradleの基本機能を紹介しているものです。Gradleを始める手助けになるでしょう。

Gradle requires a Java JDK or JRE to be installed, version 6 or higher (to check, use java -version). Gradle ships with its own Groovy library, therefore Groovy does noot need to be installed. Any existing Groovy installation is ignored by Gradle.

Gradleを使用するには、バージョン6以上のJava JDKもしくはJREが必要です(java -versionで確認してください)。 GradleにはGroovyライブラリが同梱されているので、別途Groovyをインストールする必要はありません。すでにインストールされていたとしても、Gradleでは既存のGroovyは使用されません。

Gradle uses whatever JDK it finds in your path. Alternatively, you can set the JAVA_HOME environment variable to point to the installation directory of the desired JDK.

Gradleは、システムのパス上にあるJDKを使用します。 パス上のJDKの代わりに、環境変数JAVA_HOMEにJDKをインストールしたディレクトリをセットして、使用したいJDKを指定することもできます。

You can download one of the Gradle distributions from the Gradle web site.

Gradleはウェブサイトからダウンロードできます。

The Gradle distribution comes packaged as a ZIP. The full distribution contains:

Gradleの配布物はZIPで圧縮されています。Gradleのフルパッケージには以下のものが含まれています。

For running Gradle, add GRADLE_HOME/bin to your PATH environment variable. Usually, this is sufficient to run Gradle.

GRADLE_HOME/binを環境変数PATHに追加してください。Gradleの実行に必要な環境変数の設定は、通常これだけです。

You run Gradle via the gradle command. To check if Gradle is properly installed just type gradle -v. The output shows the Gradle version and also the local environment configuration (Groovy, JVM version, OS, etc.). The displayed Gradle version should match the distribution you have downloaded.

Gradleは、gradleコマンドで実行します。Gradleが正しくインストールされていることを確認するには、gradle -vと入力してください。Gradleのバージョンとローカルの実行環境(groovyやjvmのバージョンなど)が表示されます。表示されたgradleのバージョンが、ダウンロードした配布物のバージョンと一致していることを確認してください。

JVM options for running Gradle can be set via environment variables. You can use either GRADLE_OPTS or JAVA_OPTS, or both. JAVA_OPTS is by convention an environment variable shared by many Java applications. A typical use case would be to set the HTTP proxy in JAVA_OPTS and the memory options in GRADLE_OPTS. Those variables can also be set at the beginning of the gradle or gradlew script.

Gradle実行時に引き渡すJVMオプションは、環境変数GRADLE_OPTSとJAVA_OPTSで設定します。両方一緒に使うこともできます。 JAVA_OPTSに設定したオプションは、慣習により多くのJavaアプリケーションで共有されるものです。 典型的な例で言えば、HTTPプロキシはJAVA_OPTSに設定し、使用メモリに関する設定はGRADLE_OPTSにセットする、といった使い分けが考えられるでしょう。 これらの設定はgradleやgradlewスクリプトの頭に記述することもできます。

Note that it's not currently possible to set JVM options for Gradle on the command line.

If you are encountering problems, one of the first things to try is using the very latest release of Gradle. New versions of Gradle are released frequently with bug fixes and new features. The problem you are having may have been fixed in a new release.

何かトラブルが起こったとき、まず試すことができるのは、最新版のGradleを使ってみることです。Gradleの新バージョンはバグフィックスや新機能追加のため頻繁にリリースされています。その問題は、新しいバージョンでは修正されているかもしれません。

If you are using the Gradle Daemon, try temporarily disabling the daemon (you can pass the command line switch --no-daemon). More information about troubleshooting the daemon process is located in 19章Gradleデーモン The Gradle Daemon.

Gradleデーモンを使っているなら、一時的にデーモンを停止してみてください（--no--daemonオプションをつけて実行）。 デーモン使用時のトラブルシューティングについて、詳しくは19章Gradleデーモン The Gradle Daemonを参照してください。

The place to go for help with Gradle is http://forums.gradle.org. The Gradle Forums is the place where you can report problems and ask questions of the Gradle developers and other community members.

Gradleに関して手助けを求めたいときは、http://forums.gradle.orgに行ってみましょう。 Gradleフォーラムでは、Gradleのデベロッパーやコミュニティメンバーに問題を報告したり、質問したりすることができます。

If something's not working for you, posting a question or problem report to the forums is the fastest way to get help. It's also the place to post improvement suggestions or new ideas. The development team frequently posts news items and announces releases via the forum, making it a great way to stay up to date with the latest Gradle developments.

何か問題が発生したら、フォーラムに質問や報告を投げるのが最も早く手助けを得られる方法です。 フォーラムでは、改善のための提案や新しいアイデアを投稿することもできます。 また、Gradleの開発チームが頻繁にニュースやリリースのアナウンスを投稿していますので、Gradle開発の最前線に触れるという意味でもフォーラムはとても便利です。

Everything in Gradle sits on top of two basic concepts: projects and tasks.

Gradleの根本にあるのは、プロジェクトとタスクという二つの基本的な概念です。

Every Gradle build is made up of one or more projects. What a project represents depends on what it is that you are doing with Gradle. For example, a project might represent a library JAR or a web application. It might represent a distribution ZIP assembled from the JARs produced by other projects. A project does not necessarily represent a thing to be built. It might represent a thing to be done, such as deploying your application to staging or production environments. Don't worry if this seems a little vague for now. Gradle's build-by-convention support adds a more concrete definition for what a project is.

Gradleによるビルドは、一つ以上のプロジェクトから構成されます。プロジェクトとは、ビルドされるソフトウェアを構成するコンポーネントのことですが、正確な意味は何をビルドするかによって変わります。たとえば、あるプロジェクトはライブラリjarやWebアプリケーションをビルドするものかもしれません。または、別のプロジェクトによってビルドされたjarを集めて配布用のzipファイルを作成するものかもしれません。何か具体的なものを組み立てるのではなく、処理を行うだけというプロジェクトもありえます。アプリケーションを本番環境にステージするというプロジェクトがその一例です。今は少しあいまいな印象を受けられるかもしれませんが、心配する必要はありません。Gradleは規約によるビルドをサポートしており、プロジェクトの定義については明確に規定されています。

Each project is made up of one or more tasks. A task represents some atomic piece of work which a build performs. This might be compiling some classes, creating a JAR, generating Javadoc, or publishing some archives to a repository.

それぞれのプロジェクトは、一つ以上のタスクから構成されます。タスクとは、分割不能な何らかの作業単位を表す概念です。たとえば、クラスをコンパイルしたり、JARファイルを作成したり、Javadocを生成したり、アーカイブをリポジトリに公開したりするタスクが考えられます。

For now, we will look at defining some simple tasks in a build with one project. Later chapters will look at working with multiple projects and more about working with projects and tasks.

では、実際にプロジェクト上でいくつか簡単なタスクを定義してビルドしてみましょう。マルチプロジェクトでのビルド例やプロジェクト/タスクのもっと詳しい情報については後の章をご参照ください。

You run a Gradle build using the gradle command. The gradle command looks for a file called build.gradle in the current directory. ^[3] We call this build.gradle file a build script, although strictly speaking it is a build configuration script, as we will see later. The build script defines a project and its tasks.

Gradleのビルドは、gradleコマンドで実行します。gradleコマンドはカレントディレクトリのbuild.gradleファイルを参照してビルドを行います。^[4]このファイルは、一般的にはビルドスクリプトと呼ばれます(後述しますが、正確には「ビルドの設定を行うスクリプト」です)。Gradleのプロジェクトとタスクは、このビルドスクリプトで定義されます。

To try this out, create the following build script named build.gradle.

次のようなスクリプトを、build.gradleという名前で作成して試してみてください。

task hello {
    doLast {
        println 'Hello world!'
    }
}

In a command-line shell, move to the containing directory and execute the build script with gradle -q hello:

コンソールを開いてこのbuild.gradleのあるディレクトリに移動して、gradle -q helloと打ち込んでください。ビルドスクリプトが実行され、以下のように出力されるはずです。

> gradle -q hello
Hello world!

What's going on here? This build script defines a single task, called hello, and adds an action to it. When you run gradle hello, Gradle executes the hello task, which in turn executes the action you've provided. The action is simply a closure containing some Groovy code to execute.

何が起こったのでしょう。ビルドスクリプトは、helloというタスクを一つ定義していて、このタスクにアクションを一つ追加しています。gradle helloと実行することで、Gradleがこのhelloを実行し、helloに追加したアクションが実行されたのです。アクションはGroovyコードを含む単なるクロージャです。

If you think this looks similar to Ant's targets, well, you would be right. Gradle tasks are the equivalent to Ant targets, but as you will see, they are much more powerful. We have used a different terminology than Ant as we think the word task is more expressive than the word target. Unfortunately this introduces a terminology clash with Ant, as Ant calls its commands, such as javac or copy, tasks. So when we talk about tasks, we always mean Gradle tasks, which are the equivalent to Ant's targets. If we talk about Ant tasks (Ant commands), we explicitly say Ant task.

Antのtargetに似ているなと思われたかもしれません。実際、GradleのtaskはAntでいえばtargetに相当するものです。ただ、これから見ていきますがGradleのtaskはAntのtargetよりもずっと強力なものです。Gradleではtaskという、Antとは異なる用語を採用しました。これはtaskという言葉が、targetという言葉よりも実態に合った表現だと考えたためです。しかし、残念ながらtaskという用語はAntでもcopyやjavacといったコマンドを示すものとして使われており、Gradleのtaskと競合してしまいます。このため、Antのtaskについて述べるときには常にant taskと明示的にいい、単にtaskとしたときはGradleのタスクのことを示すものとします。

There is a shorthand way to define a task like our hello task above, which is more concise.

タスク定義は、実際にはもっと短く書けます。先ほどのhelloタスクも、次のように簡潔に書くことができます。

task hello << {
    println 'Hello world!'
}

Again, this defines a task called hello with a single closure to execute. We will use this task definition style throughout the user guide.

この例も先ほどと同様、実行するクロージャを一つだけもったhelloを定義するものです。このユーザーガイドではこちらの定義方法を使用します。

Gradle's build scripts give you the full power of Groovy. As an appetizer, have a look at this:

GradleのビルドスクリプトではGroovyの機能をすべて使うことができます。手始めに次の例をご覧ください。

task upper << {
    String someString = 'mY_nAmE'
    println "Original: " + someString 
    println "Upper case: " + someString.toUpperCase()
}

> gradle -q upper
Original: mY_nAmE
Upper case: MY_NAME

or

さらに

task count << {
    4.times { print "$it " }
}

> gradle -q count
0 1 2 3

As you probably have guessed, you can declare tasks that depend on other tasks.

ご想像の通り、タスク間の依存関係を宣言できます。

task hello << {
    println 'Hello world!'
}
task intro(dependsOn: hello) << {
    println "I'm Gradle"
}

> gradle -q intro
Hello world!
I'm Gradle

To add a dependency, the corresponding task does not need to exist.

依存関係にタスクを追加するときは、そのタスクがその時点で宣言されていなくてもかまいません。

task taskX(dependsOn: 'taskY') << {
    println 'taskX'
}
task taskY << {
    println 'taskY'
}

> gradle -q taskX
taskY
taskX

The dependency of taskX to taskY is declared before taskY is defined. This is very important for multi-project builds. Task dependencies are discussed in more detail in 「タスクに依存関係を追加するAdding dependencies to a task」.

taskXがtaskYに依存していることが宣言されていますが、宣言した時点ではtaskYの定義文はありません。このことは、マルチプロジェクトのビルドで非常に重要になってきます。タスク間の依存関係については、「タスクに依存関係を追加するAdding dependencies to a task」でさらに詳しく述べられています。

Please notice, that you can't use a shortcut notation (see 「略記法Shortcut notations」) when referring to a task that is not yet defined.

なお、未定義のタスクを参照する場合、略記法(「略記法Shortcut notations」参照)は使えませんので注意してください。

The power of Groovy can be used for more than defining what a task does. For example, you can also use it to dynamically create tasks.

Groovyが力を発揮するのは、タスクが実行するアクションを記述するときだけではありません。たとえば、次のようにタスクを動的に定義することもできます。

4.times { counter ->
    task "task$counter" << {
        println "I'm task number $counter"
    }
}

> gradle -q task1
I'm task number 1

Once tasks are created they can be accessed via an API. For instance, you could use this to dynamically add dependencies to a task, at runtime. Ant doesn't allow anything like this.

タスクが公開しているAPIを使えば、既存のタスクにアクセスして定義内容を操作することができます。これはAntと異なるGradleの特長の一つです。たとえば、次のように後からタスクの依存関係を追加することができます。

4.times { counter ->
    task "task$counter" << {
        println "I'm task number $counter"
    }
}
task0.dependsOn task2, task3

> gradle -q task0
I'm task number 2
I'm task number 3
I'm task number 0

Or you can add behavior to an existing task.

また、既存のタスクにアクションを追加することもできます。

task hello << {
    println 'Hello Earth'
}
hello.doFirst {
    println 'Hello Venus'
}
hello.doLast {
    println 'Hello Mars'
}
hello << {
    println 'Hello Jupiter'
}

> gradle -q hello
Hello Venus
Hello Earth
Hello Mars
Hello Jupiter

The calls doFirst and doLast can be executed multiple times. They add an action to the beginning or the end of the task's actions list. When the task executes, the actions in the action list are executed in order. The << operator is simply an alias for doLast.

doFirstやdoLastは何回でも呼び出すことができ、既存のタスクが実行する一連のアクションの最初や最後に、新しいアクションを追加します。タスクに追加されたアクションは、タスクが実行されたときに順番に実行されます。<<はdoLastの単なるエイリアスです。

As you might have noticed in the previous examples, there is a convenient notation for accessing an existing task. Each task is available as a property of the build script:

先ほどの例をみたとき、おやっと思われたかもしれません。既存のタスクにアクセスするときは、便利な略記法を使うことができます。ただのプロパティとしてすべてのタスクにアクセスできるのです。

task hello << {
    println 'Hello world!'
}
hello.doLast {
    println "Greetings from the $hello.name task."
}

> gradle -q hello
Hello world!
Greetings from the hello task.

This enables very readable code, especially when using the tasks provided by the plugins, like the compile task.

この略記法は、コードをとても読みやすいものにします。特に、プラグインなどで外部から提供されるタスク(たとえばcompile)にアクセスするときには威力を発揮します。

You can add your own properties to a task. To add a property named myProperty, set ext.myProperty to an initial value. From that point on, the property can be read and set like a predefined task property.

独自のプロパティをタスクに追加することができます。例えば、myPropertyというプロパティを追加するには、ext.myPropertyに初期値を設定してください。 その時点で、このプロパティを定義済みのプロパティと同じように読み書きできるようになります。

task myTask {
    ext.myProperty = "myValue"
}

task printTaskProperties << {
    println myTask.myProperty
}

> gradle -q printTaskProperties
myValue

Extra properties aren't limited to tasks. You can read more about them in 「拡張プロパティ Extra properties」.

拡張プロパティを追加できるのは、タスクだけではありません。詳細については、「拡張プロパティ Extra properties」を参照してください。

Ant tasks are first-class citizens in Gradle. Gradle provides excellent integration for Ant tasks by simply by relying on Groovy. Groovy is shipped with the fantastic AntBuilder. Using Ant tasks from Gradle is as convenient and more powerful than using Ant tasks from a build.xml file. From the example below, you can learn how to execute Ant tasks and how to access Ant properties:

AntのタスクはGradleのファーストクラス・オブジェクトであり、デフォルトで使用できるようになっています。Groovyの持つ機能のおかげで、GradleはAntを非常に高いレベルで統合しています。Groovyには素晴らしきAntBuilderが組み込まれているのです。Antのタスクは、build.xmlで使うよりGradleで使ったほうが便利で強力です。次の例を見てください。Antのタスクを実行する方法やAntのプロパティにアクセスする方法を示しています。

task loadfile << {
    def files = file('../antLoadfileResources').listFiles().sort()
    files.each { File file ->
        if (file.isFile()) {
            ant.loadfile(srcFile: file, property: file.name)
            println " *** $file.name ***"
            println "${ant.properties[file.name]}"
        }
    }
}

> gradle -q loadfile
*** agile.manifesto.txt ***
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration  over contract negotiation
Responding to change over following a plan
 *** gradle.manifesto.txt ***
Make the impossible possible, make the possible easy and make the easy elegant.
(inspired by Moshe Feldenkrais)

There is lots more you can do with Ant in your build scripts. You can find out more in 17章GradleからAntを使うUsing Ant from Gradle.

Antのタスクを使ってできることはもっとたくさんあります。17章GradleからAntを使うUsing Ant from Gradleをご参照ください。

Gradle scales in how you can organize your build logic. The first level of organizing your build logic for the example above, is extracting a method.

Gradleでは、段階的にビルドロジックを体系化していくことができます。最初の一歩として、上の例をメソッドの抽出を使ってリファクタリングしてみましょう。

task checksum << {
    fileList('../antLoadfileResources').each {File file ->
        ant.checksum(file: file, property: "cs_$file.name")
        println "$file.name Checksum: ${ant.properties["cs_$file.name"]}"
    }
}

task loadfile << {
    fileList('../antLoadfileResources').each {File file ->
        ant.loadfile(srcFile: file, property: file.name)
        println "I'm fond of $file.name"
    }
}

File[] fileList(String dir) {
    file(dir).listFiles({file -> file.isFile() } as FileFilter).sort()
}

> gradle -q loadfile
I'm fond of agile.manifesto.txt
I'm fond of gradle.manifesto.txt

Later you will see that such methods can be shared among subprojects in multi-project builds. If your build logic becomes more complex, Gradle offers you other very convenient ways to organize it. We have devoted a whole chapter to this. See 60章ビルドロジックの体系化Organizing Build Logic.

後でマルチプロジェクトの各プロジェクトでメソッドを共有する方法について学びます。それでもビルドロジックが複雑になってくることもあるでしょう。Gradleでは、ロジックを体系化する便利な方法をいくつも用意しています。ビルドロジックの体系化については一つの章をすべて割り当てて取り扱っていますのでご参照ください。(60章ビルドロジックの体系化Organizing Build Logic)

Gradle allows you to define one or more default tasks for your build.

Gradleでは、ビルドに一つ以上のデフォルトタスクを定義することができます。

defaultTasks 'clean', 'run'

task clean << {
    println 'Default Cleaning!'
}

task run << {
    println 'Default Running!'
}

task other << {
    println "I'm not a default task!"
}

> gradle -q
Default Cleaning!
Default Running!

This is equivalent to running gradle clean run. In a multi-project build every subproject can have its own specific default tasks. If a subproject does not specify default tasks, the default tasks of the parent project are used (if defined).

これは、gradle clean runと入力するのと同じです。マルチプロジェクトのビルドでは、すべてのサブプロジェクトが個別にデフォルトタスクを持つことができます。サブプロジェクトにデフォルトタスクが定義されていない時は、(定義されていれば)親プロジェクトの定義が使用されます。

As we later describe in full detail (See 56章ビルドのライフサイクルThe Build Lifecycle) Gradle has a configuration phase and an execution phase. After the configuration phase, Gradle knows all tasks that should be executed. Gradle offers you a hook to make use of this information. A use-case for this would be to check if the release task is among the tasks to be executed. Depending on this, you can assign different values to some variables.

詳しくは56章ビルドのライフサイクルThe Build Lifecycleで説明しますが、Gradleのビルドはいくつかのフェーズに分かれて実行されます。Gradleはどのタスクを実行するのかを設定フェーズで決定しますが、この情報を使うためのフックが提供されています。実行タスクにあるタスクが含まれるかどうかによって、変数に別の値を割り当てたりできるわけです。ユースケースとしては、releaseタスクが実行されるタスクに入っているかどうかチェックするといったものが考えられるでしょう。

In the following example, execution of the distribution and release tasks results in different value of the version variable.

次の例では、distributionタスクを実行するかreleaseタスクを実行するかでversion変数に違う値を割り当てています。

task distribution << {
    println "We build the zip with version=$version"
}

task release(dependsOn: 'distribution') << {
    println 'We release now'
}

gradle.taskGraph.whenReady {taskGraph ->
    if (taskGraph.hasTask(release)) {
        version = '1.0'
    } else {
        version = '1.0-SNAPSHOT'
    }
}

> gradle -q distribution
We build the zip with version=1.0-SNAPSHOT

> gradle -q release
We build the zip with version=1.0
We release now

The important thing is that whenReady affects the release task before the release task is executed. This works even when the release task is not the primary task (i.e., the task passed to the gradle command).

ここで大事なことは、releaseタスクが実行予定にあるという事実を、releaseタスクが実行される前に利用できる点です。releaseタスクがプライマリタスク、つまりgradleコマンドに引き渡されているタスクでなくてもかまいません。

In this chapter, we have had a first look at tasks. But this is not the end of the story for tasks. If you want to jump into more of the details, have a look at 15章タスク詳解More about Tasks.

この章で、私たちは初めてタスクというものに触れました。しかし、タスクについての話はこれで全部ではありません。さらに詳しくタスクについて知りたい場合は、15章タスク詳解More about Tasksを見てみてください。

Otherwise, continue on to the tutorials in 7章JavaクイックスタートJava Quickstart and 8章依存関係管理の基本 Dependency Management Basics.

As we have seen, Gradle is a general-purpose build tool. It can build pretty much anything you care to implement in your build script. Out-of-the-box, however, it doesn't build anything unless you add code to your build script to do so.

ここまで見てきたように、Gradleは汎用のビルドツールです。ビルドスクリプトで実装したいと思うようなものはほぼ何でもビルドできます。しかし、初期状態では、ビルドスクリプトに何かを行うためのコードを追加しない限り、何もビルドはしません。

Most Java projects are pretty similar as far as the basics go: you need to compile your Java source files, run some unit tests, and create a JAR file containing your classes. It would be nice if you didn't have to code all this up for every project. Luckily, you don't have to. Gradle solves this problem through the use of plugins. A plugin is an extension to Gradle which configures your project in some way, typically by adding some pre-configured tasks which together do something useful. Gradle ships with a number of plugins, and you can easily write your own and share them with others. One such plugin is the Java plugin. This plugin adds some tasks to your project which will compile and unit test your Java source code, and bundle it into a JAR file.

多くのJavaプロジェクトは、基本的な部分では非常に似通っています。つまり、Javaソースファイルをコンパイルし、ユニットテストを実行し、クラスを含んだJARファイルを生成する必要があります。すべてのプロジェクトで、これらをいちいちコーディングするのは面倒です。幸運にもその必要はありません。Gradleはプラグインによってこの問題を解決します。プラグインは、何らかの方法（よくあるのは設定済みの一連の有用なタスクの追加）によってプロジェクトを構成する、Gradleの拡張です。Gradleには多くのプラグインが同梱されており、さらに自作のプラグインを書き、共有することも簡単にできます。こういったプラグインの一つがJavaプラグインです。このプラグインは、Javaソースコードのコンパイルやユニットテスト、JARファイルの作成などを行うタスクをプロジェクトに追加します。

The Java plugin is convention based. This means that the plugin defines default values for many aspects of the project, such as where the Java source files are located. If you follow the convention in your project, you generally don't need to do much in your build script to get a useful build. Gradle allows you to customize your project if you don't want to or cannot follow the convention in some way. In fact, because support for Java projects is implemented as a plugin, you don't have to use the plugin at all to build a Java project, if you don't want to.

Javaプラグインは規約ベースです。すなわち、このプラグインはプロジェクトのさまざまな点、例えばJavaソースファイルを置く場所などについてデフォルト値を定義しています。プロジェクトがこの規約に従う限り、大抵はビルドスクリプトであまり多くのことを行わなくても有用なビルドを行うことができます。何らかの事情で規約に従いたくない、または従えない場合、Gradleはプロジェクトのカスタマイズも許しています。実際、Javaプロジェクトのサポートがプラグインとして実現されているので、希望しない場合には、Javaプロジェクトのビルドであってもこのプラグインをまったく使わないことも可能です。

We have in-depth coverage with many examples about the Java plugin, dependency management and multi-project builds in later chapters. In this chapter we want to give you an initial idea of how to use the Java plugin to build a Java project.

Javaプラグイン、依存関係の管理、マルチプロジェクトのビルドについては、後の章で多くの実例付きで詳しく扱います。この章では、JavaプロジェクトをビルドするためのJavaプラグインの使い方について、まず基本的な知識を提供したいと思います。

Let's look at a simple example. To use the Java plugin, add the following to your build file:

シンプルな例から見ていきましょう。Javaプラグインを使うためには、ビルドファイルに以下を加えます：

apply plugin: 'java'

This is all you need to define a Java project. This will apply the Java plugin to your project, which adds a number of tasks to your project.

Javaプロジェクトの定義に必要なのはこれだけです。これでプロジェクトにJavaプラグインが適用され、多くのタスクが追加されます。

Gradle expects to find your production source code under src/main/java and your test source code under src/test/java. In addition, any files under src/main/resources will be included in the JAR file as resources, and any files under src/test/resources will be included in the classpath used to run the tests. All output files are created under the build directory, with the JAR file ending up in the build/libs directory.

Gradleは、製品のソースコードがsrc/main/javaに、テストのソースコードがsrc/test/javaにあることを想定しています。さらに、src/main/resourcesの下にあるファイルはすべてリソースとしてJARに入れられ、またsrc/test/resourcesにあるファイルはテスト実行時に使われるクラスパスに入れられます。すべての出力ファイルはbuildディレクトリの下に作られ、最終的にbuild/libsディレクトリにJARファイルが作られます。

> gradle build
:compileJava
:processResources
:classes
:jar
:assemble
:compileTestJava
:processTestResources
:testClasses
:test
:check
:build

BUILD SUCCESSFUL

Total time: 1 secs

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

sourceCompatibility = 1.5
version = '1.0'
jar {
    manifest {
        attributes 'Implementation-Title': 'Gradle Quickstart',
                   'Implementation-Version': version
    }
}

test {
    systemProperties 'property': 'value'
}

uploadArchives {
    repositories {
       flatDir {
           dirs 'repos'
       }
    }
}

apply plugin: 'eclipse'

apply plugin: 'java'
apply plugin: 'eclipse'

sourceCompatibility = 1.5
version = '1.0'
jar {
    manifest {
        attributes 'Implementation-Title': 'Gradle Quickstart',
                   'Implementation-Version': version
    }
}

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

test {
    systemProperties 'property': 'value'
}

uploadArchives {
    repositories {
       flatDir {
           dirs 'repos'
       }
    }
}

Now let's look at a typical multi-project build. Below is the layout for the project:

さて、ここで典型的なマルチプロジェクトのビルドを見てみましょう。プロジェクトのレイアウトは以下の通りです：

multiproject/
  api/
  services/webservice/
  shared/
  services/shared/

Here we have four projects. Project api produces a JAR file which is shipped to the client to provide them a Java client for your XML webservice. Project webservice is a webapp which returns XML. Project shared contains code used both by api and webservice. Project services/shared has code that depends on the shared project.

この例には三つのプロジェクトがあります。プロジェクトapiは、このwebサービス用のJavaクライアントを提供するために顧客に出荷されるJARファイルを生成します。プロジェクトwebserviceはXMLを返すwebアプリケーションです。プロジェクトsharedは、apiとwebserviceの両方で使われる共通コードです。

include "shared", "api", "services:webservice", "services:shared"

subprojects {
    apply plugin: 'java'
    apply plugin: 'eclipse-wtp'

    repositories {
       mavenCentral()
    }

    dependencies {
        testCompile 'junit:junit:4.11'
    }

    version = '1.0'

    jar {
        manifest.attributes provider: 'gradle'
    }
}

dependencies {
    compile project(':shared')
}

task dist(type: Zip) {
    dependsOn spiJar
    from 'src/dist'
    into('libs') {
        from spiJar.archivePath
        from configurations.runtime
    }
}

artifacts {
   archives dist
}

In this chapter, you have seen how to do some of the things you commonly need to build a Java based project. This chapter is not exhaustive, and there are many other things you can do with Java projects in Gradle. You can find out more about the Java plugin in 23章JavaプラグインThe Java Plugin, and you can find more sample Java projects in the samples/java directory in the Gradle distribution.

この章では、Javaベースのプロジェクトをビルドするときに、一般的に必要になる作業のやり方を見てきました。この章は、Javaプロジェクトについて完全に網羅しているわけではありません。Gradleでできることはもっとたくさんあります。Javaプロジェクトについて更に掘り下げたい場合は、23章JavaプラグインThe Java Pluginで詳しく知ることができます。また、Gradleの配布物に含まれるsample/javaにはもっと多くのサンプルがあります。

Otherwise, continue on to 8章依存関係管理の基本 Dependency Management Basics.

そうでない場合は、続けて8章依存関係管理の基本 Dependency Management Basicsに進んでください。

Very roughly, dependency management is made up of two pieces. Firstly, Gradle needs to know about the things that your project needs to build or run, in order to find them. We call these incoming files the dependencies of the project. Secondly, Gradle needs to build and upload the things that your project produces. We call these outgoing files the publications of the project. Let's look at these two pieces in more detail:

おおざっぱに言って、依存関係の管理とは二つの部分に分けられます。まず、Gradleは、あなたのプロジェクトをビルドしたり実行したりするのに必要なファイルが何かを判定し、それらを見つけてこなければなりません。これらの入力ファイルを、プロジェクトの依存関係と呼びます。 次に、Gradleはあなたのプロジェクトをビルドし、生成されたものをアップロードする必要があります。これらの出力ファイルを、プロジェクトの公開物と呼びます。

Most projects are not completely self-contained. They need files built by other projects in order to be compiled or tested and so on. For example, in order to use Hibernate in my project, I need to include some Hibernate jars in the classpath when I compile my source. To run my tests, I might also need to include some additional jars in the test classpath, such as a particular JDBC driver or the Ehcache jars.

ほとんどのプロジェクトは、完全に自己完結しているわけではありません。コンパイル、テスト、その他諸々のために、他のプロジェクトがビルドするファイルを必要とするものです。例えば、Hibernateを自分のプロジェクトで使うために、ソースコードのコンパイル時にHibernateのjarファイルをいくつか取り込む、といった具合です。テストをするためには、さらにいくつかのjarファイル、JDBCドライバやEhcacheのjarをテスト時クラスパスに追加する必要があるかもしれません。

These incoming files form the dependencies of the project. Gradle allows you to tell it what the dependencies of your project are, so that it can take care of finding these dependencies, and making them available in your build. The dependencies might need to be downloaded from a remote Maven or Ivy repository, or located in a local directory, or may need to be built by another project in the same multi-project build. We call this process dependency resolution.

これらの入力ファイルは、プロジェクトの依存関係から読み込まれます。 Gradleにプロジェクトの依存関係を教えて、プロジェクトが依存しているファイルを見つけたり、ビルド時にそれらを使えるようにできます。 依存ファイルは、リモートのMavenやIvyのリポジトリからダウンロードされるかもしれませんし、ローカルのディレクトリにあるかもしれません。また、マルチプロジェクトの場合、別のプロジェクトにビルドさせる必要があることもあります。

Note that this feature provides a major advantage over Ant. With Ant, you only have the ability to specify absolute or relative paths to specific jars to load. With Gradle, you simply declare the “names” of your dependencies, and other layers determine where to get those dependencies from. You can get similar behavior from Ant by adding Apache Ivy, but Gradle does it better.

Often, the dependencies of a project will themselves have dependencies. For example, Hibernate core requires several other libraries to be present on the classpath with it runs. So, when Gradle runs the tests for your project, it also needs to find these dependencies and make them available. We call these transitive dependencies.

また、依存しているファイルが、それ自身の依存関係を持っていることが多々あります。例えば、Hibernateコアは、実行時にいくつかの別のライブラリをクラスパスに含めなければなりません。なので、Gradleがあなたのプロジェクトのテストを走らせるときには、それらの依存関係も見つけてきて、使用できるようにしなければならないのです。これを、推移的な依存関係と呼びます。

The main purpose of most projects is to build some files that are to be used outside the project. For example, if your project produces a Java library, you need to build a jar, and maybe a source jar and some documentation, and publish them somewhere.

ほとんどのプロジェクトは、ファイルを作成し、それらをプロジェクトの外部で使うということを主な目的としています。 例えば、もしあなたのプロジェクトがJavaライブラリを作成するものならば、あなたはjarを作成し、ときにはソースjarやドキュメントも作成し、どこかにそれらを公開しなければなりません。

These outgoing files form the publications of the project. Gradle also takes care of this important work for you. You declare the publications of your project, and Gradle take care of building them and publishing them somewhere. Exactly what “publishing” means depends on what you want to do. You might want to copy the files to a local directory, or upload them to a remote Maven or Ivy repository. Or you might use the files in another project in the same multi-project build. We call this process publication.

ファイルの公開は、プロジェクトの公開設定から読み込まれて行われます。Gradleは、この重要な仕事も引き受けてくれます。プロジェクトが公開するファイルを宣言すれば、Gradleがそれらをビルドし、任意の場所へ公開します。 「公開する」ということの正確な意味は、何をしたいのかによって異なります。ローカルディレクトリにファイルをコピーしたいかもしれませんし、リモートのMavenやIvyのリポジトリにアップロードしたいかもしれません。また、マルチプロジェクトの場合、別プロジェクトからそのファイルを使いたいという場合もあります。 これらの処理を、公開と呼んでいます。

Let's look at some dependency declarations. Here's a basic build script:

さて、では依存関係の宣言についていくつか見ていきましょう。ここに、ある基本的なビルドスクリプトがあります。

apply plugin: 'java'

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'org.hibernate', name: 'hibernate-core', version: '3.6.7.Final'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

What's going on here? This build script says a few things about the project. Firstly, it states that Hibernate core 3.6.7.Final is required to compile the project's production source. By implication, Hibernate core and its dependencies are also required at runtime. The build script also states that any junit >= 4.0 is required to compile the project's tests. It also tells Gradle to look in the Maven central repository for any dependencies that are required. The following sections go into the details.

一体、何が起きるでしょうか。このビルドスクリプトにはそれほど多くの情報はありません。まず、このプロジェクトはソースコードをコンパイルするためにHibernate core 3.6.7を使用すると言っています。それはすなわち、実行時にHibernate coreとその依存関係が必要になるということでもあります。 このスクリプトはまた、バージョン4.0以上のJUnitのどれかを、プロジェクトのテストをコンパイルするのに必要とするとも言っています。さらに、Gradleに、全ての依存関係を見つけるのにMavenのセントラルリポジトリを探すように指示しています。次の節で、それぞれの詳細について見ていきましょう。

In Gradle dependencies are grouped into configurations. A configuration is simply a named set of dependencies. We will refer to them as dependency configurations. You can use them to declare the external dependencies of your project. As we will see later, they are also used to declare the publications of your project.

Gradleでは、依存関係は、コンフィグレーションによってグループ化されます。コンフィグレーションとは、単なる名前の付いた依存関係の集まりです。コンフィグレーションは依存関係設定として参照されます。プロジェクトが外部に依存しているものを宣言するのに使われ、また後で見るように、プロジェクトが外部に公開するものを宣言するためにも使用されます。

The Java plugin defines a number of standard configurations. These configurations represent the classpaths that the Java plugin uses. Some are listed below, and you can find more details in 表23.5「Javaプラグイン - 依存関係のコンフィギュレーションJava plugin - dependency configurations」.

Javaプラグインは、いくつかの標準コンフィグレーションを定義します。これらのコンフィグレーションは、Javaプラグインが使用するクラスパスを表すものです。いくつかを以下にリストしました。詳細については、表23.5「Javaプラグイン - 依存関係のコンフィギュレーションJava plugin - dependency configurations」を参照してください。

Various plugins add further standard configurations. You can also define your own custom configurations to use in your build. Please see 「依存関係のコンフィギュレーション Dependency configurations」 for the details of defining and customizing dependency configurations.

多くのプラグインが、このような標準コンフィグレーションを追加します。また、自分のビルドに使うためのカスタムコンフィギュレーションを独自に定義することもできます。依存関係のコンフィグレーション定義やカスタマイズの詳細については、「依存関係のコンフィギュレーション Dependency configurations」を参照してください。

There are various types of dependencies that you can declare. One such type is an external dependency. This a dependency on some files built outside the current build, and stored in a repository of some kind, such as Maven central, or a corporate Maven or Ivy repository, or a directory in the local file system.

定義できる依存関係には、さまざまなタイプがあります。そのうちの一つが、外部依存関係です。これは、今のビルドとは別に作られ、MavenセントラルリポジトリやIvyリポジトリ、ローカルファイルシステムなどに保存されているファイルへの依存関係です。

To define an external dependency, you add it to a dependency configuration:

外部依存関係を定義するには、それを依存関係のコンフィグレーションに追加します。

dependencies {
    compile group: 'org.hibernate', name: 'hibernate-core', version: '3.6.7.Final'
}

An external dependency is identified using group, name and version attributes. Depending on which kind of repository you are using, group and version may be optional.

外部依存関係は、group属性、name属性、そしてversion属性を用いて定義します。 使用しているリポジトリの種類によっては、group属性とversion属性はオプショナルになるかもしれません。

The shortcut form for declaring external dependencies looks like “group:name:version”.

There is a shortcut form for declaring external dependencies, which uses a string of the form "group:name:version".

外部依存関係を定義するときは、ショートカット形式を使うこともできます。"group:name:version"という文字列を使う形式です。

dependencies {
    compile 'org.hibernate:hibernate-core:3.6.7.Final'
}

To find out more about defining and working with dependencies, have a look at 「依存関係の定義方法 How to declare your dependencies」.

依存関係を定義して取り扱う方法について、詳しくは「依存関係の定義方法 How to declare your dependencies」を見てください。

How does Gradle find the files for external dependencies? Gradle looks for them in a repository. A repository is really just a collection of files, organized by group, name and version. Gradle understands several different repository formats, such as Maven and Ivy, and several different ways of accessing the repository, such as using the local file system or HTTP.

Gradleは、どうやって外部依存関係を見つけるのでしょうか？　Gradleは、それらをリポジトリから探します。リポジトリの実体は、ただのファイルの集合です。それらのファイルは、グループ、名前、そしてバージョンによって分類されています。Gradleは、MavenやIvyなど、様々なリポジトリ形式に対応できます。また、ローカルファイルシステムやHTTPなど、リポジトリにアクセスするための手段についても様々なものを使うことができます。

By default, Gradle does not define any repositories. You need to define at least one before you can use external dependencies. One option is use the Maven central repository:

デフォルトでは、Gradleはリポジトリを一切定義していません。外部依存関係を使うには、少なくとも一つのリポジトリを定義する必要があります。 選択肢の一つは、Mavenのセントラルリポジトリを使うことです。

repositories {
    mavenCentral()
}

Or a remote Maven repository:

または、別のMavenリモートリポジトリを使います。

repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
    }
}

Or a remote Ivy repository:

または、リモートのIvyリポジトリを使います。

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
    }
}

You can also have repositories on the local file system. This works for both Maven and Ivy repositories.

さらに、ローカルファイルシステム上にリポジトリを持つこともできます。これは、Maven、Ivy双方のリポジトリ形式で動作します。

repositories {
    ivy {
        // URL can refer to a local directory
        url "../local-repo"
    }
}

A project can have multiple repositories. Gradle will look for a dependency in each repository in the order they are specified, stopping at the first repository that contains the requested module.

一つのプロジェクトが、複数のリポジトリを持つことができます。Gradleは、それぞれのリポジトリを、指定された順序で順に探しに行きます。要求されたモジュールが含まれる、最初のリポジトリを見つけるまで走査を続けます。

To find out more about defining and working with repositories, have a look at 「リポジトリ Repositories」.

リポジトリを定義し、取り扱う方法について、詳しくは「リポジトリ Repositories」を参照してください。

Dependency configurations are also used to publish files.^[5] We call these files publication artifacts, or usually just artifacts.

依存関係のコンフィグレーションは、ファイルを公開するのにも使用します。^[6] これらのファイルを、公開アーティファクト、大体は単にアーティファクトと呼びます。

The plugins do a pretty good job of defining the artifacts of a project, so you usually don't need to do anything special to tell Gradle what needs to be published. However, you do need to tell Gradle where to publish the artifacts. You do this by attaching repositories to the uploadArchives task. Here's an example of publishing to a remote Ivy repository:

プラグインが非常に適切にプロジェクトのアーティファクトを定義してくれるので、何を公開したいかGradleに教えるのに、特別何かする必要はほとんどの場合ありません。ただ、どこに公開したいかはGradleに教えてやる必要があります。これは、リポジトリをuploadArchivesタスクに結びつけることで行います。次のコードは、リモートのIvyリポジトリに公開する例です。

uploadArchives {
    repositories {
        ivy {
            credentials {
                username "username"
                password "pw"
            }
            url "http://repo.mycompany.com"
        }
    }
}

Now, when you run gradle uploadArchives, Gradle will build and upload your Jar. Gradle will also generate and upload an ivy.xml as well.

これでgradle uploadArchivesを走らせれば、Gradleがjarをビルドしてアップロードしてくれます。 さらに、ivy.xmlも生成されてアップロードされます。

You can also publish to Maven repositories. The syntax is slightly different.^[7] Note that you also need to apply the Maven plugin in order to publish to a Maven repository. when this is in place, Gradle will generate and upload a pom.xml.

Mavenリポジトリに公開することもできますが、その文法はすこし異なります^[8]。 また、Mavenリポジトリへ公開するには、Mavenプラグインを使う必要もあるので注意してください。この場合、Gradleはpom.xmlも生成してアップロードします。

apply plugin: 'maven'

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: "file://localhost/tmp/myRepo/")
        }
    }
}

To find out more about publication, have a look at 52章アーティファクトの公開 Publishing artifacts.

アーティファクトの公開について、詳しくは52章アーティファクトの公開 Publishing artifactsをご参照ください。

For all the details of dependency resolution, see 51章依存関係の管理 Dependency Management, and for artifact publication see 52章アーティファクトの公開 Publishing artifacts.

依存関係解決については、51章依存関係の管理 Dependency Managementに全て詳細に載っています。そして、アーティファクトの公開については52章アーティファクトの公開 Publishing artifactsに載っています。

If you are interested in the DSL elements mentioned here, have a look at Project.configurations{}, Project.repositories{} and Project.dependencies{}.

本章で使ったDSLに興味があるのであれば、Project.configurations{}やProject.repositories{}、Project.dependencies{}を見てください。

Otherwise, continue on to some of the other tutorials.

それ以外の場合は、チュートリアルから他のチュートリアルを進めてください。

Let's look at an example. To use the Groovy plugin, add the following to your build file:

実例を見てみましょう。Groovyプラグインを使うためには、ビルドファイルに以下を記述を追加します：

apply plugin: 'groovy'

This will also apply the Java plugin to the project, if it has not already been applied. The Groovy plugin extends the compile task to look for source files in directory src/main/groovy, and the compileTest task to look for test source files in directory src/test/groovy. The compile tasks use joint compilation for these directories, which means they can contain a mixture of Java and Groovy source files.

これにより、（もしまだなら）プロジェクトにはJavaプラグインも適用されます。Groovyプラグインはcompileタスクを拡張してsrc/main/groovyディレクトリにあるソースファイルも参照するようにし、またcompileTestタスクを拡張してsrc/test/groovyディレクトリにあるテスト用ソースファイルも参照するようにします。compileタスクはこれらのディレクトリに対してジョイントコンパイルを使うので、javaとgroovyのソースファイルが混在していてもかまいません。

To use the Groovy compilation tasks, you must also declare the Groovy version to use and where to find the Groovy libraries. You do this by adding a dependency to the groovy configuration. The compile configuration inherits this dependency, so the Groovy libraries will be included in classpath when compiling Groovy and Java source. For our sample, we will use Groovy 2.2.0 from the public Maven repository:

Groovy用のcompileタスクを使うには、GroovyのバージョンとGroovyライブラリを探してくる場所を宣言する必要があります。これは、compileコンフィギュレーションに依存関係を追加することによって行います。この例では、Groovy 2.2.0を使用します。

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.codehaus.groovy:groovy-all:2.3.6'
}

Here is our complete build file:

以下にビルドファイルの全体を示します：

apply plugin: 'eclipse'
apply plugin: 'groovy'

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.codehaus.groovy:groovy-all:2.3.6'
    testCompile 'junit:junit:4.11'
}

Running gradle build will compile, test and JAR your project.

gradle buildを実行すれば、プロジェクトがコンパイル、テストされ、JARが生成されます。

This chapter describes a very simple Groovy project. Usually, a real project will require more than this. Because a Groovy project is a Java project, whatever you can do with a Java project, you can also do with a Groovy project.

この章では非常にシンプルなGroovyプロジェクトについて説明しました。通常、実プロジェクトではこの例よりもっと複雑な記述が必要でしょう。GroovyプロジェクトはJavaプロジェクトでもあるので、Javaプロジェクトで可能なことなら何でもGroovyプロジェクトでも可能です。

You can find out more about the Groovy plugin in 24章GroovyプラグインThe Groovy Plugin, and you can find more sample Groovy projects in the samples/groovy directory in the Gradle distribution.

24章GroovyプラグインThe Groovy Pluginでは、Groovyプラグインをより詳しく説明しています。また、Gradle配布物のsamples/groovyディレクトリには、Groovyプロジェクトの実例が多く含まれています。

To build a WAR file, you apply the War plugin to your project:

WARファイルをビルドするために、プロジェクトにWarプラグインを適用します:

apply plugin: 'war'

This also applies the Java plugin to your project. Running gradle build will compile, test and WAR your project. Gradle will look for the source files to include in the WAR file in src/main/webapp. Your compiled classes and their runtime dependencies are also included in the WAR file, in the WEB-INF/classes and WEB-INF/lib directories, respectively.

これにより、プロジェクトにはJavaプラグインも適用されます。 gradle buildを実行すれば、プロジェクトがコンパイル、テストされ、WARが生成されます。 Gradleはsrc/main/webappにあるファイルからWARに含めるものを探します。 コンパイル済みクラスや実行時に必要となる依存ライブラリもWARに追加されます。

To run your web application, you apply the Jetty plugin to your project:

Webアプリケーションを実行するためには、プロジェクトにJettyプラグインを適用します:

apply plugin: 'jetty'

This also applies the War plugin to your project. Running gradle jettyRun will run your web application in an embedded Jetty web container. Running gradle jettyRunWar will build the WAR file, and then run it in an embedded web container.

これにより、プロジェクトにはWarプラグインも適用されます。 gradle jettyRunを実行すれば、組み込みJettyコンテナ上でWebアプリケーションが実行されます。 gradle jettyRunWarを実行するとWARファイルが生成され、その後組み込みWebコンテナで実行されます。

TODO: which url, configure port, uses source files in place and can edit your files and reload.

TODO: URLの確認方法、ポートの設定、ソースファイルの編集と動的リロードの方法など

You can find out more about the War plugin in 26章War プラグインThe War Plugin and the Jetty plugin in 28章Jetty プラグインThe Jetty Plugin. You can find more sample Java projects in the samples/webApplication directory in the Gradle distribution.

Warプラグインについての詳細は26章War プラグインThe War Plugin、 Jettyプラグインの詳細については28章Jetty プラグインThe Jetty Pluginを参照してください。 Gradle配布物のsamples/webApplicationディレクトリにサンプルJavaプロジェクトがあります。

You can execute multiple tasks in a single build by listing each of the tasks on the command-line. For example, the command gradle compile test will execute the compile and test tasks. Gradle will execute the tasks in the order that they are listed on the command-line, and will also execute the dependencies for each task. Each task is executed once only, regardless of how it came to be included in the build: whether it was specified on the command-line, or as a dependency of another task, or both. Let's look at an example.

一回のビルドで、複数のタスクを実行することができます。ビルドを実行するときに、タスクを並べて指定してください。たとえば、gradle compile testというコマンドを実行すれば、compileタスクとtestタスクが実行されます。Gradleはタスクを列挙された順に実行するほか、それらが依存しているタスクも実行します。また、タスクが実行されるのはそれぞれ一度だけです。コマンドラインで明示的に指定されたタスクも、それらに依存して実行されるタスクも、またその両方に含まれるタスクも同様です。次の例を見てください。

Below four tasks are defined. Both dist and test depend on the compile task. Running gradle dist test for this build script results in the compile task being executed only once.

この例では、四つのタスクが定義されており、distとtestはどちらもcompileタスクに依存しています。このビルドスクリプトを呼び出してgradle dist testと実行しても、実行された二つのタスクから依存されているcompileタスクは一度だけしか実行されません。

図11.1 Task間の依存関係Task dependencies

task compile << {
    println 'compiling source'
}

task compileTest(dependsOn: compile) << {
    println 'compiling unit tests'
}

task test(dependsOn: [compile, compileTest]) << {
    println 'running unit tests'
}

task dist(dependsOn: [compile, test]) << {
    println 'building the distribution'
}

> gradle dist test
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs

Each task is executed only once only, so gradle test test is exactly the same as gradle test.

タスクが一度だけ実行されるということは、gradle test testと打ち込んでもgradle testと打ち込んでも、実行される処理は全く同じだということです。

You can exclude a task from being executed using the -x command-line option and providing the name of the task to exclude. Let's try this with the sample build file above.

-xオプションでタスクの名前を指定することで、そのタスクを除外してビルドを実行することができます。先ほどのサンプルで試してみましょう。

> gradle dist -x test
:compile
compiling source
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs

You can see from the output of this example, that the test task is not executed, even though it is a dependency of the dist task. You will also notice that the test task's dependencies, such as compileTest are not executed either. Those dependencies of test that are required by another task, such as compile, are still executed.

distタスクはtestに依存しているのですが、この例ではtestタスクは実行されていないことが分かります。また、testタスクが依存しているタスク、たとえばcompileTestタスクもやはり実行されていません。しかし、testタスクが依存しているタスクのうち、test以外からも依存されているタスク、つまりcompileタスクは実行されているのです。

By default, Gradle will abort execution and fail the build as soon as any task fails. This allows the build to complete sooner, but hides other failures that would have occurred. In order to discover as many failures as possible in a single build execution, you can use the --continue option.

デフォルトでは、タスクが失敗するとすぐにGradleは実行を中止してビルドを失敗させます。これはビルドの完了は早くなりますが、発生するかもしれない他のエラーを隠してしまうかもしれません。 一回のビルド実行でできるだけ多くのエラーを発見するには、--continueオプションを使用します。

When executed with --continue, Gradle will execute every task to be executed where all of the dependencies for that task completed without failure, instead of stopping as soon as the first failure is encountered. Each of the encountered failures will be reported at the end of the build.

--continueオプションをつけてビルドすると、エラー発生時に即ビルドが停止されるのではなく、失敗せずに完了したタスクに依存するタスクは全て実行されるようになります。 また、ビルド中に発生したエラーはビルド終了時に全てレポートされます。

If a task fails, any subsequent tasks that were depending on it will not be executed, as it is not safe to do so. For example, tests will not run if there is a compilation failure in the code under test; because the test task will depend on the compilation task (either directly or indirectly).

タスクが失敗した場合、依存関係上の後続タスクは安全に実行できないため行われません。 例えば、テストの際、コードのコンパイルでエラーが発生するとテストは実施されません。テストタスクはコンパイルタスクに直接的、間接的に依存しているからです。

When you specify tasks on the command-line, you don't have to provide the full name of the task. You only need to provide enough of the task name to uniquely identify the task. For example, in the sample build above, you can execute task dist by running gradle d:

タスク名をコマンドラインで指定するとき、タスク名をすべて入力する必要はありません。タスク名を一つに決定できるだけの文字を入力すればよいのです。先ほどの例で言えば、gradle dと入力すればdistを実行できます。

> gradle di
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution

BUILD SUCCESSFUL

Total time: 1 secs

You can also abbreviate each word in a camel case task name. For example, you can execute task compileTest by running gradle compTest or even gradle cT

キャメルケースで分割されたそれぞれの単語を省略することもできます。たとえば、compileTestというタスクだと、gradle compTestと入力したり、gradle cTと入力したりすることで実行できます。

> gradle cT
:compile
compiling source
:compileTest
compiling unit tests

BUILD SUCCESSFUL

Total time: 1 secs

You can also use these abbreviations with the -x command-line option.

-xオプションで除外タスクを指定するときにも、同じようにタスク名を省略できます。

When you run the gradle command, it looks for a build file in the current directory. You can use the -b option to select another build file. If you use -b option then settings.gradle file is not used. Example:

gradleコマンドは、デフォルトではカレントディレクトリにあるビルドスクリプトを探して実行しますが、-bオプションを使えば別のビルドスクリプトを指定することもできます。次の例を見てください。 なお、-bを使うと、settings.gradleファイルは使用されなくなります。

task hello << {
    println "using build file '$buildFile.name' in '$buildFile.parentFile.name'."
}

> gradle -q -b subdir/myproject.gradle hello
using build file 'myproject.gradle' in 'subdir'.

Alternatively, you can use the -p option to specify the project directory to use. For multi-project builds you should use -p option instead of -b option.

別の方法として、-pオプションを指定して、使用するプロジェクトディレクトリを変更することもできます。 マルチプロジェクトの場合は、-bオプションでなく-pオプションを使用するべきです。

> gradle -q -p subdir hello
using build file 'build.gradle' in 'subdir'.

Gradle provides several built-in tasks which show particular details of your build. This can be useful for understanding the structure and dependencies of your build, and for debugging problems.

ビルドに関する様々な情報を表示するために、組み込みのタスクがいくつか用意されています。自分の作ったビルドが今どんな構造になっているのか調べたり、何か問題が起こったときにデバッグしたりするのに役立つはずです。

In addition to the built-in tasks shown below, you can also use the project report plugin to add tasks to your project which will generate these reports.

この組み込みタスクに加えて、プロジェクトレポートプラグインというプラグインを使うこともできます。このプラグインは、これらの情報をレポートに保存するタスクをプロジェクトに追加してくれます。

> gradle -q projects
------------------------------------------------------------
Root project
------------------------------------------------------------

Root project 'projectReports'
+--- Project ':api' - The shared API for the application
\--- Project ':webapp' - The Web application implementation

To see a list of the tasks of a project, run gradle <project-path>:tasks
For example, try running gradle :api:tasks

description = 'The shared API for the application'

> gradle -q tasks
------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Default tasks: dists

Build tasks
-----------
clean - Deletes the build directory (build)
dists - Builds the distribution
libs - Builds the JAR

Build Setup tasks
-----------------
init - Initializes a new Gradle build. [incubating]
wrapper - Generates Gradle wrapper files. [incubating]

Help tasks
----------
components - Displays the components produced by root project 'projectReports'.
dependencies - Displays all dependencies declared in root project 'projectReports'.
dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
help - Displays a help message.
projects - Displays the sub-projects of root project 'projectReports'.
properties - Displays the properties of root project 'projectReports'.
tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).

To see all tasks and more detail, run with --all.

dists {
    description = 'Builds the distribution'
    group = 'build'
}

> gradle -q tasks --all
------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Default tasks: dists

Build tasks
-----------
clean - Deletes the build directory (build)
api:clean - Deletes the build directory (build)
webapp:clean - Deletes the build directory (build)
dists - Builds the distribution [api:libs, webapp:libs]
    docs - Builds the documentation
api:libs - Builds the JAR
    api:compile - Compiles the source files
webapp:libs - Builds the JAR [api:libs]
    webapp:compile - Compiles the source files

Build Setup tasks
-----------------
init - Initializes a new Gradle build. [incubating]
wrapper - Generates Gradle wrapper files. [incubating]

Help tasks
----------
components - Displays the components produced by root project 'projectReports'.
api:components - Displays the components produced by project ':api'.
webapp:components - Displays the components produced by project ':webapp'.
dependencies - Displays all dependencies declared in root project 'projectReports'.
api:dependencies - Displays all dependencies declared in project ':api'.
webapp:dependencies - Displays all dependencies declared in project ':webapp'.
dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
api:dependencyInsight - Displays the insight into a specific dependency in project ':api'.
webapp:dependencyInsight - Displays the insight into a specific dependency in project ':webapp'.
help - Displays a help message.
api:help - Displays a help message.
webapp:help - Displays a help message.
projects - Displays the sub-projects of root project 'projectReports'.
api:projects - Displays the sub-projects of project ':api'.
webapp:projects - Displays the sub-projects of project ':webapp'.
properties - Displays the properties of root project 'projectReports'.
api:properties - Displays the properties of project ':api'.
webapp:properties - Displays the properties of project ':webapp'.
tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).
api:tasks - Displays the tasks runnable from project ':api'.
webapp:tasks - Displays the tasks runnable from project ':webapp'.

> gradle -q help --task libs
Detailed task information for libs

Paths
     :api:libs
     :webapp:libs

Type
     Task (org.gradle.api.Task)

Description
     Builds the JAR

> gradle -q dependencies api:dependencies webapp:dependencies
------------------------------------------------------------
Root project
------------------------------------------------------------

No configurations

------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------

compile
\--- org.codehaus.groovy:groovy-all:2.3.6

testCompile
\--- junit:junit:4.11
     \--- org.hamcrest:hamcrest-core:1.3

------------------------------------------------------------
Project :webapp - The Web application implementation
------------------------------------------------------------

compile
+--- project :api
|    \--- org.codehaus.groovy:groovy-all:2.3.6
\--- commons-io:commons-io:1.2

testCompile
No dependencies

> gradle -q api:dependencies --configuration testCompile
------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------

testCompile
\--- junit:junit:4.11
     \--- org.hamcrest:hamcrest-core:1.3

> gradle -q webapp:dependencyInsight --dependency groovy --configuration compile
org.codehaus.groovy:groovy-all:2.3.6
\--- project :api
     \--- compile

> gradle -q api:properties
------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------

allprojects: [project ':api']
ant: org.gradle.api.internal.project.DefaultAntBuilder@12345
antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345
artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler_Decorated@12345
asDynamicObject: org.gradle.api.internal.ExtensibleDynamicObject@12345
baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345
buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build
buildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradle

11.6.7. ビルドのプロファイリングProfiling a build

The --profile command line option will record some useful timing information while your build is running and write a report to the build/reports/profile directory. The report will be named using the time when the build was run.

コマンドラインオプションで--profileをつけてビルドを実行すると、ビルドに要した時間のうち有用と思われるいくつかの情報を計測して、結果をbuild/reports/profileディレクトリを出力します。レポート名には、ビルドを行った時刻が付加されます。

This report lists summary times and details for both the configuration phase and task execution. The times for configuration and task execution are sorted with the most expensive operations first. The task execution results also indicate if any tasks were skipped (and the reason) or if tasks that were not skipped did no work.

このレポートでは、ビルド時間に関する概要のほか、設定フェーズとタスク実行に要した時間がタスクごとに表示されます。設定フェーズ、タスク実行に関するレポートは必要時間の降順でソートされており、さらにタスク実行については、タスクがスキップされたかどうか、作業が発生したかどうかみることができるようになっています。

Builds which utilize a buildSrc directory will generate a second profile report for buildSrc in the buildSrc/build directory.

なお、buildSrcディレクトリを使っている場合、buildSrc/buildにbuildSrcのレポートが別途出力されます。

Sometimes you are interested in which tasks are executed in which order for a given set of tasks specified on the command line, but you don't want the tasks to be executed. You can use the -m option for this. For example, if you run “gradle -m clean compile”, you'll see all the tasks that would be executed as part of the clean and compile tasks. This is complementary to the tasks task, which shows you the tasks which are available for execution.

コマンドラインにタスク名を並べて実行したときに、どのタスクがどの順番で実行されるのか知りたくなることがあります。しかしそのために実際にタスクを実行したくはありません。このような場合、-mオプションをつけて実行してください。たとえば、gradle -m clean compileと実行すれば、cleanタスクとcompileタスクの実行にあたって実際に実行されるすべてのタスクが実行順に表示されます。これは、実行可能なタスクの一覧を表示するtasksタスクの補足にもなります。

In this chapter, you have seen some of the things you can do with Gradle from the command-line. You can find out more about the gradle command in 付録D Gradle コマンドラインGradle Command Line.

この章では、コマンドラインで使えるGradleの機能をいくつか見てきました。gradleコマンドについては付録D Gradle コマンドラインGradle Command Lineにも記載してあります。

The Task Tree shows a hierarchical display of all projects and their tasks. Double clicking a task executes it.

Task Treeは、すべてのプロジェクトとタスクの階層構造を表示します。タスクをダブルクリックすると、そのタスクが実行されます。

There is also a filter so that uncommon tasks can be hidden. You can toggle the filter via the Filter button. Editing the filter allows you to configure which tasks and projects are shown. Hidden tasks show up in red. Note: newly created tasks will show up by default (versus being hidden by default).

また、フィルターも用意されているので、一般的でないタスクは非表示にすることができます。フィルターを有効にするかどうかはFilterボタンで切り替えできます。 フィルター編集画面では、どのタスクとプロジェクトを表示するかを設定します。非表示に設定されたタスクは赤色で強調されます。 注意: 新しく作成されたタスクは、デフォルトでは表示に設定されます（デフォルトで非表示に設定されるのではなく）。

The Task Tree context menu provides the following options:

タスクツリーのコンテキストメニューでは、以下の機能も使うことができます。

The Favorites tab is a good place to store commonly-executed commands. These can be complex commands (anything that's legal to Gradle) and you can provide them with a display name. This is useful for creating, say, a custom build command that explicitly skips tests, documentation, and samples that you could call “fast build”.

Favoriteタブでは、よく実行するコマンドをお気に入りとして保存できます。保存するコマンドは複雑なもの（Gradleにとって正しいものならなんでもかまいません）でもよく、わかりやすい表示名をつけることもできます。お気に入りは、テストやドキュメンテーション、サンプル作成などを明示的にスキップする、"急速なビルド"と呼べるようなカスタムビルドを作成するのに便利だと言えます。

You can reorder favorites to your liking and even export them to disk so they can imported by others. If you edit them, you are given options to “Always Show Live Output”. This only applies if you have “Only Show Output When Errors Occur”. This override always forces the output to be shown.

The Command Line tab is where you can to execute a single Gradle command directly. Just enter whatever you would normally enter after 'gradle' on the command line. This also provides a place to try out commands before adding them to favorites.

The Setup tab allows configuration of some general settings.

Setupタブは、一般的な設定を行うところです。

図12.2 GUI Setup

Gradle provides a domain specific language, or DSL, for describing builds. This build language is based on Groovy, with some additions to make it easier to describe a build.

Gradleは、ビルドシステムを記述するためのドメイン特化言語(DSL)を提供します。 このビルド用言語は、Groovyをベースに、ビルドシステムの記述を簡単にするための機能をいくつか追加したものです。

A build script can contain any Groovy language element. ^[9] Gradle assumes that each build script is encoded using UTF-8.

In the tutorial in 7章JavaクイックスタートJava Quickstart we used, for example, the apply() method. Where does this method come from? We said earlier that the build script defines a project in Gradle. For each project in the build, Gradle creates an object of type Project and associates this Project object with the build script. As the build script executes, it configures this Project object:

例えば、7章JavaクイックスタートJava Quickstartのチュートリアルで使用したapply()メソッド、このメソッドはどこから来たのでしょうか。まず、前述のようにビルドスクリプトはGradleのプロジェクトを定義します。 ビルドに含まれるプロジェクトそれぞれに対し、Project型のインスタンスが一つ作られ、ビルドスクリプトと関連づけられます。ビルドが実行されると、このプロジェクト・インスタンスは以下のように振る舞います。

Let's try this out and try to access the name property of the Project object.

プロジェクトオブジェクトのnameプロパティにアクセスして試してみましょう。

println name
println project.name

> gradle -q check
projectApi
projectApi

Both println statements print out the same property. The first uses auto-delegation to the Project object, for properties not defined in the build script. The other statement uses the project property available to any build script, which returns the associated Project object. Only if you define a property or a method which has the same name as a member of the Project object, would you need to use the project property.

どちらのprintlnも出力結果は同じです。最初のprintlnは、ビルドスクリプトで定義されていないプロパティへのアクセスを、暗黙のうちにプロジェクトオブジェクトに委譲しています。もう一方の例では、プロジェクトオブジェクトを返すprojectプロパティを使って、nameにアクセスしています。projectプロパティには、ビルドスクリプトのどこからでもアクセスできます。プロジェクトオブジェクトのプロパティやメソッドと同名のものをビルドスクリプトに定義している場合は、projectプロパティからアクセスすることになるでしょう。

When Gradle executes a script, it compiles the script into a class which implements Script. This means that all of the properties and methods declared by the Script interface are available in your script.

ビルドスクリプトが実行されるときは、スクリプトはScriptを実装したクラスにコンパイルされます。つまり、ビルドスクリプトではScriptインターフェースで宣言されているプロパティとメソッドを全て使うことができるということです。

There are two kinds of variables that can be declared in a build script: local variables and extra properties.

ビルドスクリプトでは、二つの方法で変数を宣言できます。ローカル変数と拡張プロパティです。

def dest = "dest"

task copy(type: Copy) {
    from "source"
    into dest
}

apply plugin: "java"

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"
    }
}

task printProperties << {
    println springVersion
    println emailNotification
    sourceSets.matching { it.purpose == "production" }.each { println it.name }
}

> gradle -q printProperties
3.1.0.RELEASE
build@master.org
main
plugin

Groovy provides plenty of features for creating DSLs, and the Gradle build language takes advantage of these. Understanding how the build language works will help you when you write your build script, and in particular, when you start to write custom plugins and tasks.

// Iterable gets an each() method
configurations.runtime.each { File f -> println f }

// Using a getter method
println project.buildDir
println getProject().getBuildDir()

// Using a setter method
project.buildDir = 'target'
getProject().setBuildDir('target')

test.systemProperty 'some.prop', 'value'
test.systemProperty('some.prop', 'value')

// List literal
test.includes = ['org/gradle/api/**', 'org/gradle/internal/**']

List<String> list = new ArrayList<String>()
list.add('org/gradle/api/**')
list.add('org/gradle/internal/**')
test.includes = list

// Map literal.
Map<String, String> map = [key1:'value1', key2: 'value2']

// Groovy will coerce named arguments
// into a single map argument
apply plugin: 'java'

repositories {
    println "in a closure"
}
repositories() { println "in a closure" }
repositories({ println "in a closure" })

dependencies {
    assert delegate == project.dependencies
    testCompile('junit:junit:4.11')
    delegate.testCompile('junit:junit:4.11')
}

There is a common situation where multiple tasks depend on the existence of a directory. Of course you can deal with this by adding a mkdir to the beginning of those tasks, but it's almost always a bad idea to repeat a sequence of code that you only need once (Look up the DRY principle). A better solution would use the dependsOn relationship between tasks to reuse the task to create the directory:

複数のタスクが、ある一つのディレクトリが存在していることを前提としている、ということがよくあります。 それらのタスク全てでmkdirを呼ぶことももちろんできますが、それではやはり冗長です。 この場合、次のように、ディレクトリを必要とするタスクにdependsOn関係を追加するのが良い方法です。

def classesDir = new File('build/classes')

task resources << {
    classesDir.mkdirs()
    // do something
}
task compile(dependsOn: 'resources') << {
    if (classesDir.isDirectory()) {
        println 'The class directory exists. I can operate'
    }
    // do something
}

> gradle -q compile
The class directory exists. I can operate

Gradle offers a variety of ways to add properties to your build. With the -D command line option you can pass a system property to the JVM which runs Gradle. The -D option of the gradle command has the same effect as the -D option of the java command.

Gradleでは、さまざまな方法でビルドにプロパティ値を渡すことができます。 -Dオプションを使えばGradleを実行しているJVMにシステムプロパティを渡すことができます。 gradleコマンドは-Dオプションをjavaコマンドへの-Dオプションと同じように処理します。

You can also directly add properties to your project objects using properties files. You can place a gradle.properties file in the Gradle user home directory (defined by the “GRADLE_USER_HOME” environment variable, which if not set defaults to USER_HOME/.gradle) or in your project directory. For multi-project builds you can place gradle.properties files in any subproject directory. The properties set in a gradle.properties file can be accessed via the project object. The properties file in the user's home directory has precedence over property files in the project directories.

propertiesファイルを記述することで、projectオブジェクトに直接プロパティを追加することもできます。 このプロパティファイルgradle.propertiesはGradleのホームディレクトリ (デフォルトではUSER_HOME/.gradle)かプロジェクトディレクトリに作成します。 マルチプロジェクトの場合、gradle.properteisはすべてのサブプロジェクトディレクトリに置くことができます。 gradle.propertiesに記述されたプロパティはprojectオブジェクトからアクセスすることができます。 なお、ホームディレクトリのgradle.propertiesは、プロジェクトディレクトリのgradle.propertiesの定義を上書きし、優先的に使用されます。

You can also add properties directly to your project object via the -P command line option.

projectオブジェクトに追加するプロパティは、コマンドラインオプションの-Pオプションで直接設定することもできます。

Gradle can also set project properties when it sees specially-named system properties or environment variables. This feature is very useful when you don't have admin rights to a continuous integration server and you need to set property values that should not be easily visible, typically for security reasons. In that situation, you can't use the -P option, and you can't change the system-level configuration files. The correct strategy is to change the configuration of your continuous integration build job, adding an environment variable setting that matches an expected pattern. This won't be visible to normal users on the system. ^[10]

projectオブジェクトに追加するプロパティは、コマンドラインオプションの-Pオプションで設定することもできます。また、さらにエキゾチックな使い方に備えて、環境変数やシステムプロパティからプロパティを直接取り込む機能もあります。たとえば、管理権限のないマシン上のCIサーバーで継続的なビルドを行う場合について考えてみましょう。自分のビルドスクリプトに、他人から見られたくない値をプロパティとして設定する必要がある場合、-Pオプションは使えません。このときは、プロジェクトの管理者のみアクセスできるようなCIサーバー上のページで環境変数を設定することで、ビルドスクリプトにプロパティを渡すことができます。 ^[11] ここで設定する環境変数名にはあるパターンがあり、ORG_GRADLE_PROJECT_propertyName=somevalueという環境変数を設定した場合propertyNameというプロパティがプロジェクトに設定されます。また、システムプロパティでも同様のメカニズムを実装しています。パターンがorg.gradle.project.propertyNameとなっていること以外は環境変数の場合と同じです。

If the environment variable name looks like ORG_GRADLE_PROJECT_prop=somevalue, then Gradle will set a prop property on your project object, with the value of somevalue. Gradle also supports this for system properties, but with a different naming pattern, which looks like org.gradle.project.prop.

You can also set system properties in the gradle.properties file. If a property name in such a file has the prefix “systemProp.”, like “systemProp.propName”, then the property and its value will be set as a system property, without the prefix. In a multi project build, “systemProp.” properties set in any project except the root will be ignored. That is, only the root project's gradle.properties file will be checked for properties that begin with the “systemProp.” prefix.

gradle.propertiesファイルでもシステムプロパティを設定することができます。 ファイル内でプレフィックスにsystemPropをつけてプロパティを設定することで、プレフィックス部分をのぞいたプロパティ名でシステムプロパティに追加されます。

gradlePropertiesProp=gradlePropertiesValue
sysProp=shouldBeOverWrittenBySysProp
envProjectProp=shouldBeOverWrittenByEnvProp
systemProp.system=systemValue

task printProps << {
    println commandLineProjectProp
    println gradlePropertiesProp
    println systemProjectProp
    println envProjectProp
    println System.properties['system']
}

> gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps
commandLineProjectPropValue
gradlePropertiesValue
systemPropertyValue
envPropertyValue
systemValue

You can configure the current project using an external build script. All of the Gradle build language is available in the external script. You can even apply other scripts from the external script.

外部のビルドスクリプトを取り込んでプロジェクトを設定することができます。取り込む外部スクリプト内では、Gradleの文法がすべて使用できます。その外部スクリプトから、さらに別の外部スクリプトを取り込むことさえ可能です。

apply from: 'other.gradle'

println "configuring $project"
task hello << {
    println 'hello from other script'
}

> gradle -q hello
configuring root project 'configureProjectUsingScript'
hello from other script

You can configure arbitrary objects in the following very readable way.

次のような非常に読みやすい方法で、あらゆるオブジェクトを設定することができます。

task configure << {
    def pos = configure(new java.text.FieldPosition(10)) {
        beginIndex = 1
        endIndex = 5
    }
    println pos.beginIndex
    println pos.endIndex
}

> gradle -q configure
1
5

You can also configure arbitrary objects using an external script.

外部スクリプトを使って、任意のオブジェクトを組み立てることもできます。

task configure << {
    def pos = new java.text.FieldPosition(10)
    // Apply the script
    apply from: 'other.gradle', to: pos
    println pos.beginIndex
    println pos.endIndex
}

> gradle -q configure
1
5

To improve responsiveness Gradle caches all compiled scripts by default. This includes all build scripts, initialization scripts, and other scripts. The first time you run a build for a project, Gradle creates a .gradle directory in which it puts the compiled script. The next time you run this build, Gradle uses the compiled script, if the script has not changed since it was compiled. Otherwise the script gets compiled and the new version is stored in the cache. If you run Gradle with the --recompile-scripts option, the cached script is discarded and the script is compiled and stored in the cache. This way you can force Gradle to rebuild the cache.

応答速度を上げるため、Gradleはコンパイル済みのスクリプトをデフォルトですべてキャッシュします。キャッシュ対象には、すべてのビルドスクリプトや初期化スクリプトなどが含まれます。最初にプロジェクトをビルドしたとき、Gradleは.gradleディレクトリをプロジェクトディレクトリに作成します。そこにコンパイル済みのスクリプトが保存され、次回のビルドからは、そのコンパイル済みのスクリプトが使用されるのです。もし前回コンパイルしたときからスクリプトが変更されていれば、キャッシュは再度コンパイルされます。--recompile-scriptsオプションをつけてGradleを実行すれば、キャッシュはすべて破棄され、再度コンパイル、保存されます。これにより、Gradleにキャッシュを再構築させることができます。

We have already seen how to define tasks using a keyword style in 6章ビルドスクリプトの基本Build Script Basics. There are a few variations on this style, which you may need to use in certain situations. For example, the keyword style does not work in expressions.

「6章ビルドスクリプトの基本Build Script Basics」で、キーワードを使ったタスク定義を紹介しましたが、タスクの定義方法は他にも少しあります。ときには、それらの方法が必要になることもあるでしょう。たとえば、式の中ではキーワード形式の定義方法を使うことができません。

task(hello) << {
    println "hello"
}

task(copy, type: Copy) {
    from(file('srcDir'))
    into(buildDir)
}

You can also use strings for the task names:

タスク名に文字列を使うこともできます。

task('hello') <<
{
    println "hello"
}

task('copy', type: Copy) {
    from(file('srcDir'))
    into(buildDir)
}

There is an alternative syntax for defining tasks, which you may prefer to use:

他にもいくつかシンタックスが用意されています。もしかすると、これらのシンタックスの方が好みに合うという人もいるかもしれません。

tasks.create(name: 'hello') << {
    println "hello"
}

tasks.create(name: 'copy', type: Copy) {
    from(file('srcDir'))
    into(buildDir)
}

Here we add tasks to the tasks collection. Have a look at TaskContainer for more variations of the create() method.

この例では、tasksコレクションにタスクを追加しています。create()メソッドのバリエーションについてはTaskContainerをご参照ください。

You often need to locate the tasks that you have defined in the build file, for example, to configure them or use them for dependencies. There are a number of ways of doing this. Firstly, each task is available as a property of the project, using the task name as the property name:

ビルドファイルから、定義済みのタスクを探して取得したい、というケースがよくあります。例えば、既存のタスクの設定を変更したり、依存関係を定義するために参照したいといった場面です。タスクを取得する方法はたくさんありますが、まずはプロジェクトのプロパティとしてアクセスする方法を見てみましょう。タスク名がプロパティ名として使用できます。

task hello

println hello.name
println project.hello.name

Tasks are also available through the tasks collection.

tasksコレクションからタスクを持ってくることもできます。

task hello

println tasks.hello.name
println tasks['hello'].name

You can access tasks from any project using the task's path using the tasks.getByPath() method. You can call the getByPath() method with a task name, or a relative path, or an absolute path.

tasks.getByPath()を使えば、あらゆるプロジェクトのタスクにアクセスできます。getByPath()にはタスク名のほか、タスクの相対パスや絶対パスを渡すことが可能です。

project(':projectA') {
    task hello
}

task hello

println tasks.getByPath('hello').path
println tasks.getByPath(':hello').path
println tasks.getByPath('projectA:hello').path
println tasks.getByPath(':projectA:hello').path

> gradle -q hello
:hello
:hello
:projectA:hello
:projectA:hello

Have a look at TaskContainer for more options for locating tasks.

そのほかの方法については、TaskContainerをご参照ください。

As an example, let's look at the Copy task provided by Gradle. To create a Copy task for your build, you can declare in your build script:

例として、Gradleに用意されているCopyタスクを見てみましょう。Copyタスクを自分のビルドで作成するには、ビルドスクリプトで次のように宣言します。

task myCopy(type: Copy)

This creates a copy task with no default behavior. The task can be configured using its API (see Copy). The following examples show several different ways to achieve the same configuration.

作成されたコピータスクには、デフォルトでは何の動作も設定されていません。 タスクは、タスクのAPI(Copy参照)を使って設定することができます。 次のいくつかの例は、どれも同じ設定を行うものです。

Just to be clear, realize that the name of this task is “myCopy”, but it is of type “Copy”. You can have multiple tasks of the same type, but with different names. You'll find this gives you a lot of power to implement cross-cutting concerns across all tasks of a particular type.

Copy myCopy = task(myCopy, type: Copy)
myCopy.from 'resources'
myCopy.into 'target'
myCopy.include('**/*.txt', '**/*.xml', '**/*.properties')

This is similar to the way we would configure objects in Java. You have to repeat the context (myCopy) in the configuration statement every time. This is a redundancy and not very nice to read.

これは、普段私たちがJavaオブジェクトを設定するのと同じ方法で設定する方法です。この方法では、設定処理を呼び出すたびに同じコンテキスト(myCopy)を何度も書く必要があります。これは冗長だし、あまり可読性もよくありません。

There is another way of configuring a task. It also preserves the context and it is arguably the most readable. It is usually our favorite.

タスクの設定には別の方法があります。この方法でも同様にコンテキストは保持されますし、おそらく最も可読性の高い方法です。私たちは、普段この方法を好んで使っています。

task myCopy(type: Copy)

myCopy {
   from 'resources'
   into 'target'
   include('**/*.txt', '**/*.xml', '**/*.properties')
}

This works for any task. Line 3 of the example is just a shortcut for the tasks.getByName() method. It is important to note that if you pass a closure to the getByName() method, this closure is applied to configure the task, not when the task executes.

この方法は、あらゆるタスクで使用できます。3行目のコードは、tasks.getByName()の単なるショートカットです。大事なことは、getByName()メソッドにクロージャを渡すと、そのクロージャがタスクが実行されるときではなく、設定されるときに適用されるという点です。

You can also use a configuration closure when you define a task.

また、タスクを定義するときに、同時に設定クロージャを使うこともできます。

task copy(type: Copy) {
   from 'resources'
   into 'target'
   include('**/*.txt', '**/*.xml', '**/*.properties')
}

There are several ways you can define the dependencies of a task. In 「タスクの依存関係Task dependencies」 you were introduced to defining dependencies using task names. Task names can refer to tasks in the same project as the task, or to tasks in other projects. To refer to a task in another project, you prefix the name of the task with the path of the project it belongs to. The following is an example which adds a dependency from projectA:taskX to projectB:taskY:

タスクの依存関係を定義する方法はいくつかあります。「タスクの依存関係Task dependencies」では、タスク名を使って依存関係を定義する方法を紹介しました。タスク名を使うと、同じプロジェクトのタスク、または別のプロジェクトのタスクも参照できます。別のプロジェクトのタスクを参照するには、タスク名に、そのタスクが属しているプロジェクトのパスをプレフィックスとして付けてください。次の例では、projectA:taskXからprojectB:taskYへの依存関係を定義しています。

project('projectA') {
    task taskX(dependsOn: ':projectB:taskY') << {
        println 'taskX'
    }
}

project('projectB') {
    task taskY << {
        println 'taskY'
    }
}

> gradle -q taskX
taskY
taskX

Instead of using a task name, you can define a dependency using a Task object, as shown in this example:

タスク名を使う代わりに、次の例のように、Taskオブジェクトを使って依存関係を定義することも出来ます。

task taskX << {
    println 'taskX'
}

task taskY << {
    println 'taskY'
}

taskX.dependsOn taskY

> gradle -q taskX
taskY
taskX

For more advanced uses, you can define a task dependency using a closure. When evaluated, the closure is passed the task whose dependencies are being calculated. The closure should return a single Task or collection of Task objects, which are then treated as dependencies of the task. The following example adds a dependency from taskX to all the tasks in the project whose name starts with lib:

より上級ユーザー向けの方法として、クロージャを使って依存関係を定義することが出来ます。評価フェーズ時に、そのクロージャは、依存関係を算出中のタスクに渡されます。そのクロージャは、一つのTaskオブジェクトかTaskオブジェクトのコレクションを返さなければなりません。返されたタスクが依存タスクとして設定されます。次の例では、taskXから、名前がlibで始まる全てのタスクへの依存関係を設定しています。

task taskX << {
    println 'taskX'
}

taskX.dependsOn {
    tasks.findAll { task -> task.name.startsWith('lib') }
}

task lib1 << {
    println 'lib1'
}

task lib2 << {
    println 'lib2'
}

task notALib << {
    println 'notALib'
}

> gradle -q taskX
lib1
lib2
taskX

For more information about task dependencies, see the Task API.

さらにタスクの依存関係に関する情報を得るには、Task APIを参照してください。

In some cases it is useful to control the order in which 2 tasks will execute, without introducing an explicit dependency between those tasks. The primary difference between a task ordering and a task dependency is that an ordering rule does not influence which tasks will be executed, only the order in which they will be executed.

Task ordering can be useful in a number of scenarios:

There are two ordering rules available: “must run after” and “should run after”.

When you use the “must run after” ordering rule you specify that taskB must always run after taskA, whenever both taskA and taskB will be run. This is expressed as taskB.mustRunAfter(taskA). The “should run after” ordering rule is similar but less strict as it will be ignored in two situations. Firstly if using that rule introduces an ordering cycle. Secondly when using parallel execution and all dependencies of a task have been satisfied apart from the “should run after” task, then this task will be run regardless of whether its “should run after” dependencies have been run or not. You should use “should run after” where the ordering is helpful but not strictly required.

With these rules present it is still possible to execute taskA without taskB and vice-versa.

task taskX << {
    println 'taskX'
}
task taskY << {
    println 'taskY'
}
taskY.mustRunAfter taskX

> gradle -q taskY taskX
taskX
taskY

task taskX << {
    println 'taskX'
}
task taskY << {
    println 'taskY'
}
taskY.shouldRunAfter taskX

> gradle -q taskY taskX
taskX
taskY

In the examples above, it is still possible to execute taskY without causing taskX to run:

> gradle -q taskY
taskY

To specify a “must run after” or “should run after” ordering between 2 tasks, you use the Task.mustRunAfter() and Task.shouldRunAfter() methods. These methods accept a task instance, a task name or any other input accepted by Task.dependsOn().

Note that “B.mustRunAfter(A)” or “B.shouldRunAfter(A)” does not imply any execution dependency between the tasks:

As mentioned before, the “should run after” ordering rule will be ignored if it introduces an ordering cycle:

task taskX << {
    println 'taskX'
}
task taskY << {
    println 'taskY'
}
task taskZ << {
    println 'taskZ'
}
taskX.dependsOn taskY
taskY.dependsOn taskZ
taskZ.shouldRunAfter taskX

> gradle -q taskX
taskZ
taskY
taskX

You can add a description to your task. This description is displayed when executing gradle tasks.

定義したタスクに、説明書きを追加できます。追加した説明は、たとえばgradle tasksを実行したときなどに表示されます。

task copy(type: Copy) {
   description 'Copies the resource directory to the target directory.'
   from 'resources'
   into 'target'
   include('**/*.txt', '**/*.xml', '**/*.properties')
}

Sometimes you want to replace a task. For example, if you want to exchange a task added by the Java plugin with a custom task of a different type. You can achieve this with:

ときには、タスクを置き換えたくなることがあります。例えば、Javaプラグインによって追加されたタスクを、別のタイプのカスタムタスクに入れ替えたいといった場合です。これは、次のようにして実現できます。

task copy(type: Copy)

task copy(overwrite: true) << {
    println('I am the new one.')
}

> gradle -q copy
I am the new one.

This will replace a task of type Copy with the task you've defined, because it uses the same name. When you define the new task, you have to set the overwrite property to true. Otherwise Gradle throws an exception, saying that a task with that name already exists.

ここでは、Copyタイプのタスクを、シンプルな別のタスクに置き換えています。タスクを作成するときに、overwriteプロパティをtrueにセットしなければなりません。そうしないと、Gradleは例外を投げ、すでに同名のタスクが定義済みだと警告してきます。

Gradle offers multiple ways to skip the execution of a task.

Gradleは、タスクの実行をスキップする方法を複数用意しています。

task hello << {
    println 'hello world'
}

hello.onlyIf { !project.hasProperty('skipHello') }

> gradle hello -PskipHello
:hello SKIPPED

BUILD SUCCESSFUL

Total time: 1 secs

task compile << {
    println 'We are doing the compile.'
}

compile.doFirst {
    // Here you would put arbitrary conditions in real life.
    // But this is used in an integration test so we want defined behavior.
    if (true) { throw new StopExecutionException() }
}
task myTask(dependsOn: 'compile') << {
   println 'I am not affected'
}

> gradle -q myTask
I am not affected

task disableMe << {
    println 'This should not be printed if the task is disabled.'
}
disableMe.enabled = false

> gradle disableMe
:disableMe SKIPPED

BUILD SUCCESSFUL

Total time: 1 secs

If you are using one of the tasks that come with Gradle, such as a task added by the Java plugin, you might have noticed that Gradle will skip tasks that are up-to-date. This behaviour is also available for your tasks, not just for built-in tasks.

JavaプラグインのようなGradleが提供しているタスクを使ったとき、Gradleが未更新(UP-TO-DATE)のタスクをスキップすることに気づかれたかもしれません。この動作は、ビルドインのタスクだけでなく、任意のタスクに組み込むことができます。

task transform {
    ext.srcFile = file('mountains.xml')
    ext.destDir = new File(buildDir, 'generated')
    doLast {
        println "Transforming source file."
        destDir.mkdirs()
        def mountains = new XmlParser().parse(srcFile)
        mountains.mountain.each { mountain ->
            def name = mountain.name[0].text()
            def height = mountain.height[0].text()
            def destFile = new File(destDir, "${name}.txt")
            destFile.text = "$name -> ${height}\n"
        }
    }
}

> gradle transform
:transform
Transforming source file.

> gradle transform
:transform
Transforming source file.

task transform {
    ext.srcFile = file('mountains.xml')
    ext.destDir = new File(buildDir, 'generated')
    inputs.file srcFile
    outputs.dir destDir
    doLast {
        println "Transforming source file."
        destDir.mkdirs()
        def mountains = new XmlParser().parse(srcFile)
        mountains.mountain.each { mountain ->
            def name = mountain.name[0].text()
            def height = mountain.height[0].text()
            def destFile = new File(destDir, "${name}.txt")
            destFile.text = "$name -> ${height}\n"
        }
    }
}

> gradle transform
:transform
Transforming source file.

> gradle transform
:transform UP-TO-DATE

Sometimes you want to have a task whose behavior depends on a large or infinite number value range of parameters. A very nice and expressive way to provide such tasks are task rules:

ときには、広範囲、または無限大な範囲のパラメータに応じた動作を行うタスクを定義したくなることがあります。このようなタスクを定義するための、表現力のあるよい方法がタスクルールです。

tasks.addRule("Pattern: ping<ID>") { String taskName ->
    if (taskName.startsWith("ping")) {
        task(taskName) << {
            println "Pinging: " + (taskName - 'ping')
        }
    }
}

> gradle -q pingServer1
Pinging: Server1

The String parameter is used as a description for the rule, which is shown with gradle tasks.

文字列が引数に渡されていますが、これはルールの説明として使用されます。例えば、gradle tasksを実行したときなどに表示されます。

Rules not only used when calling tasks from the command line. You can also create dependsOn relations on rule based tasks:

ルールは、ただコマンドラインからのタスク呼び出しにのみ使えるものではありません。dependsOnによる依存関係定義のときも、ルールベースのタスクを使うことができます。

tasks.addRule("Pattern: ping<ID>") { String taskName ->
    if (taskName.startsWith("ping")) {
        task(taskName) << {
            println "Pinging: " + (taskName - 'ping')
        }
    }
}

task groupPing {
    dependsOn pingServer1, pingServer2
}

> gradle -q groupPing
Pinging: Server1
Pinging: Server2

If you run “gradle -q tasks” you won't find a task named “pingServer1” or “pingServer2”, but this script is executing logic based on the request to run those tasks.

Finalizer tasks are automatically added to the task graph when the finalized task is scheduled to run.

task taskX << {
    println 'taskX'
}
task taskY << {
    println 'taskY'
}

taskX.finalizedBy taskY

> gradle -q taskX
taskX
taskY

Finalizer tasks will be executed even if the finalized task fails.

task taskX << {
    println 'taskX'
    throw new RuntimeException()
}
task taskY << {
    println 'taskY'
}

taskX.finalizedBy taskY

> gradle -q taskX
taskX
taskY

On the other hand, finalizer tasks are not executed if the finalized task didn't do any work, for example if it is considered up to date or if a dependent task fails.

Finalizer tasks are useful in situations where the build creates a resource that has to be cleaned up regardless of the build failing or succeeding. An example of such a resource is a web container that is started before an integration test task and which should be always shut down, even if some of the tests fail.

To specify a finalizer task you use the Task.finalizedBy() method. This method accepts a task instance, a task name, or any other input accepted by Task.dependsOn().

If you are coming from Ant, an enhanced Gradle task like Copy seems like a cross between an Ant target and an Ant task. Although Ant's tasks and targets are really different entities, Gradle combines these notions into a single entity. Simple Gradle tasks are like Ant's targets, but enhanced Gradle tasks also include aspects of Ant tasks. All of Gradle's tasks share a common API and you can create dependencies between them. These tasks are much easier to configure than an Ant task. They make full use of the type system, and are more expressive and easier to maintain.

以前にAntを使ったことがあれば、Copyのような拡張タスクは、Antのターゲットとタスクの間をとったようなものに見えるでしょう。 Antのタスクとターゲットは実際には異なるエンティティですが、Gradleはこれらの記法を1つのエンティティにまとめています。 単純なGradleのタスクはAntのターゲットのようなものだし、拡張タスクはAntタスクの性質を含んでいます。 すべてのGradleタスクは、同じのAPIを共有していて、タスク間の依存関係を定義することができます。 このため、GradleのタスクはAntタスクに比べて、より設定しやすいものになっているでしょう。 Gradleのタスクは、型システムをフル活用しており、より表現力豊かで、メンテナンス性もよくなっています。

You can locate a file relative to the project directory using the Project.file() method.

Project.file() メソッドで、プロジェクトディレクトリからの相対参照でファイルを取得できます。

// Using a relative path
File configFile = file('src/config.xml')

// Using an absolute path
configFile = file(configFile.absolutePath)

// Using a File object with a relative path
configFile = file(new File('src/config.xml'))

You can pass any object to the file() method, and it will attempt to convert the value to an absolute File object. Usually, you would pass it a String or File instance. If this path is an absolute path, it is used to construct a File instance. Otherwise, a File instance is constructed by prepending the project directory path to the supplied path. The file() method also understands URLs, such as file:/some/path.xml.

file()メソッドには、あらゆるオブジェクトを渡すことができます。渡したオブジェクトは、絶対参照のFileに変換されます。大抵はStringかFileのインスタンスを渡すことになるでしょう。渡されたオブジェクトのtoString()が呼ばれ、その返値がファイルパスとして使われます。もしそのパスが絶対パスだった場合、そのパスでFileインスタンスが構築されます。そうでなければ、プロジェクトディレクリのパスを先頭に追加してからFileインスタンスが構築されます。また、file()メソッドはfile:/some/path.xmlのようなURLにも対応しています。

Using this method is a useful way to convert some user provided value into an absolute File. It is preferable to using new File(somePath), as file() always evaluates the supplied path relative to the project directory, which is fixed, rather than the current working directory, which can change depending on how the user runs Gradle.

このメソッドを使って、ユーザーが指定した値を簡単に絶対参照のFileインスタンスに変換できます。 これは、new File(somePath)を使うよりもよい方法でしょう。file()メソッドは、常にプロジェクトディレクリからの相対参照で解決されるからです。ワーキングディレクトリはGradleをどう実行したかによって変化しうるわけですが、それに依存せずにファイルを参照できます。

A file collection is simply a set of files. It is represented by the FileCollection interface. Many objects in the Gradle API implement this interface. For example, dependency configurations implement FileCollection.

ファイルコレクションは、単なるファイルの集合です。これは、FileCollectionインターフェースで表現されます。Gradle APIに含まれる多くのオブジェクトがこのインターフェースを実装しています。例えば、依存関係のコンフィグレーションもこのFileCollectionインターフェースを実装しています。

One way to obtain a FileCollection instance is to use the Project.files() method. You can pass this method any number of objects, which are then converted into a set of File objects. The files() method accepts any type of object as its parameters. These are evaluated relative to the project directory, as per the file() method, described in 「ファイルを参照する Locating files」. You can also pass collections, iterables, maps and arrays to the files() method. These are flattened and the contents converted to File instances.

FileCollectionを取得する方法の一つは、Project.files()メソッドを使うことです。このメソッドには任意の数のオブジェクトを渡すことができ、渡したオブジェクトはFileオブジェクトの集合に変換されます。これらのオブジェクトは、「ファイルを参照する Locating files」で述べたfile()メソッドと同じように、プロジェクトディレクトリからの相対参照で解決されます。 また、コレクション、イテレーブル、マップ、配列を渡すこともできます。これらは、フラット化されてから、各要素がFileインスタンスに変換されます。

FileCollection collection = files('src/file1.txt',
                                  new File('src/file2.txt'),
                                  ['src/file3.txt', 'src/file4.txt'])

A file collection is iterable, and can be converted to a number of other types using the as operator. You can also add 2 file collections together using the + operator, or subtract one file collection from another using the - operator. Here are some examples of what you can do with a file collection.

ファイルコレクションはイテレーブルです。さらに、as演算子で様々な型に変換することができます。 また、二つのファイルコレクションを+演算子で合成したり、-演算子でファイルコレクションから別のファイルコレクションの要素を取り除いたりすることができます。 次の例は、ファイルコレクションでどのようなことができるかを示すものです。

// Iterate over the files in the collection
collection.each {File file ->
    println file.name
}

// Convert the collection to various types
Set set = collection.files
Set set2 = collection as Set
List list = collection as List
String path = collection.asPath
File file = collection.singleFile
File file2 = collection as File

// Add and subtract collections
def union = collection + files('src/file3.txt')
def different = collection - files('src/file3.txt')

You can also pass the files() method a closure or a Callable instance. This is called when the contents of the collection are queried, and its return value is converted to a set of File instances. The return value can be an object of any of the types supported by the files() method. This is a simple way to 'implement' the FileCollection interface.

files()メソッドには、クロージャやCallableのインスタンスを渡すこともできます。 これはそのファイルコレクションの内容が要求されたときに実行され、返値がFileインスタンスの集合に変換されます。返値はfiles()に渡すことができるオブジェクトならなんでも構いません。これは、FileCollectionインタフェースを簡単に「実装する」方法とも言えます。

task list << {
    File srcDir

    // Create a file collection using a closure
    collection = files { srcDir.listFiles() }

    srcDir = file('src')
    println "Contents of $srcDir.name"
    collection.collect { relativePath(it) }.sort().each { println it }

    srcDir = file('src2')
    println "Contents of $srcDir.name"
    collection.collect { relativePath(it) }.sort().each { println it }
}

> gradle -q list
Contents of src
src/dir1
src/file1.txt
Contents of src2
src2/dir1
src2/dir2

Some other types of things you can pass to files():

他にもいくつかfiles()メソッドに渡せる型があります。

It is important to note that the content of a file collection is evaluated lazily, when it is needed. This means you can, for example, create a FileCollection that represents files which will be created in the future by, say, some task.

留意すべき重要な点は、ファイルコレクションの内容は、必要になったときに遅延評価されるということです。 これはつまり、例えば未来にタスクなどによって作られるであろうファイル群を表すFileCollectionを作ることもできる、ということを意味します。

A file tree is a collection of files arranged in a hierarchy. For example, a file tree might represent a directory tree or the contents of a ZIP file. It is represented by the FileTree interface. The FileTree interface extends FileCollection, so you can treat a file tree exactly the same way as you would a file collection. Several objects in Gradle implement the FileTree interface, such as source sets.

ファイルツリーは、階層構造を持つファイルの集合です。例えば、ディレクトリツリーやZIPの中身を表すことができます。ファイルツリーはFileTreeインターフェースによって表現されます。FileTreeインターフェースはFileCollectionインターフェースを継承しています。なので、FileTreeはFileCollectionと全く同じ方法で取り扱うことができます。 いくつかのGradleオブジェクトはFileTreeを実装しています。例えば、ソースセットなどです。

One way to obtain a FileTree instance is to use the Project.fileTree() method. This creates a FileTree defined with a base directory, and optionally some Ant-style include and exclude patterns.

FileTreeインスタンスを取得する方法の一つは、Project.fileTree()メソッドを使用することです。 このメソッドは、ベースディレクトリとAntスタイルのinclude/excludeパターンを指定してFileTreeを構築します。

// Create a file tree with a base directory
FileTree tree = fileTree(dir: 'src/main')

// Add include and exclude patterns to the tree
tree.include '**/*.java'
tree.exclude '**/Abstract*'

// Create a tree using path
tree = fileTree('src').include('**/*.java')

// Create a tree using closure
tree = fileTree('src') {
    include '**/*.java'
}

// Create a tree using a map
tree = fileTree(dir: 'src', include: '**/*.java')
tree = fileTree(dir: 'src', includes: ['**/*.java', '**/*.xml'])
tree = fileTree(dir: 'src', include: '**/*.java', exclude: '**/*test*/**')

You use a file tree in the same way you use a file collection. You can also visit the contents of the tree, and select a sub-tree using Ant-style patterns:

ファイルツリーは、ファイルコレクションと同じ方法で使うことができます。さらに、ツリー構造を辿ったり、Antスタイルのパターンを指定してサブツリーを選択することも可能です。

// Iterate over the contents of a tree
tree.each {File file ->
    println file
}

// Filter a tree
FileTree filtered = tree.matching {
    include 'org/gradle/api/**'
}

// Add trees together
FileTree sum = tree + fileTree(dir: 'src/test')

// Visit the elements of the tree
tree.visit {element ->
    println "$element.relativePath => $element.file"
}

You can use the contents of an archive, such as a ZIP or TAR file, as a file tree. You do this using the Project.zipTree() and Project.tarTree() methods. These methods return a FileTree instance which you can use like any other file tree or file collection. For example, you can use it to expand the archive by copying the contents, or to merge some archives into another.

ZIPやTARファイルなどのアーカイブを、ファイルツリーとして使うことができます。そのためのメソッドが、Project.zipTree()やProject.tarTree()です。これらのメソッドは、FileTreeインスタンスを返すもので、返されたインスタンスは、他のファイルツリーやファイルコレクションと同様に扱うことができます。 例えば、内容をコピーすることでアーカイブを解凍したり、別のアーカイブとマージしたりできます。

// Create a ZIP file tree using path
FileTree zip = zipTree('someFile.zip')

// Create a TAR file tree using path
FileTree tar = tarTree('someFile.tar')

//tar tree attempts to guess the compression based on the file extension
//however if you must specify the compression explicitly you can:
FileTree someTar = tarTree(resources.gzip('someTar.ext'))

Many objects in Gradle have properties which accept a set of input files. For example, the JavaCompile task has a source property, which defines the source files to compile. You can set the value of this property using any of the types supported by the files() method, which was shown above. This means you can set the property using, for example, a File, String, collection, FileCollection or even a closure. Here are some examples:

多くのGradleオブジェクトが入力ファイルセットを格納できるプロパティを持っています。例えば、JavaCompileタスクにはsourceプロパティがあり、コンパイルするべきソースファイルの集合をそこに定義します。 このプロパティの値には、files()でサポートされている、上記の全ての型が使用可能です。 つまり、File、String、コレクション、FileCollection、クロージャでさえセット可能ということです。次の例を見てください。

// Use a File object to specify the source directory
compile {
    source = file('src/main/java')
}

// Use a String path to specify the source directory
compile {
    source = 'src/main/java'
}

// Use a collection to specify multiple source directories
compile {
    source = ['src/main/java', '../shared/java']
}

// Use a FileCollection (or FileTree in this case) to specify the source files
compile {
    source = fileTree(dir: 'src/main/java').matching { include 'org/gradle/api/**' }
}

// Using a closure to specify the source files.
compile {
    source = {
        // Use the contents of each zip file in the src dir
        file('src').listFiles().findAll {it.name.endsWith('.zip')}.collect { zipTree(it) }
    }
}

Usually, there is a method with the same name as the property, which appends to the set of files. Again, this method accepts any of the types supported by the files() method.

大抵、そのプロパティと同名のメソッドも定義されていて、そのメソッドでファイルセットを追加できるようになっています。このメソッドにもfiles()でサポートされている全ての型を渡すことができます。

compile {
    // Add some source directories use String paths
    source 'src/main/java', 'src/main/groovy'

    // Add a source directory using a File object
    source file('../shared/java')

    // Add some source directories using a closure
    source { file('src/test/').listFiles() }
}

You can use the Copy task to copy files. The copy task is very flexible, and allows you to, for example, filter the contents of the files as they are copied, and map to the file names.

Copyタスクを使ってファイルをコピーできます。このタスクはとても柔軟で、コピーしたファイルの内容をフィルターにかけたり、ファイル名をマッピングで変換したりできます。

To use the Copy task, you must provide a set of source files to copy, and a destination directory to copy the files to. You may also specify how to transform the files as they are copied. You do all this using a copy spec. A copy spec is represented by the CopySpec interface. The Copy task implements this interface. You specify the source files using the CopySpec.from() method. To specify the destination directory, use the CopySpec.into() method.

Copyタスクを使うには、コピーすべきソースファイルと、コピー先のディレクトリを指定しなければなりません。また、コピー時にファイルを編集する場合は、それについても指定します。これらの指定は全て、Copy仕様を使って行います。Copy仕様は、CopySpecインターフェースで表現されており、Copyタスクはこのインターフェースを実装したものです。ソースファイルの指定には、CopySpec.from()メソッドを使います。コピー先ディレクトリの指定には、CopySpec.into()メソッドを使います。

task copyTask(type: Copy) {
    from 'src/main/webapp'
    into 'build/explodedWar'
}

The from() method accepts any of the arguments that the files() method does. When an argument resolves to a directory, everything under that directory (but not the directory itself) is recursively copied into the destination directory. When an argument resolves to a file, that file is copied into the destination directory. When an argument resolves to a non-existing file, that argument is ignored. If the argument is a task, the output files (i.e. the files the task creates) of the task are copied and the task is automatically added as a dependency of the Copy task. The into() accepts any of the arguments that the file() method does. Here is another example:

from()メソッドが受け付ける型は、files()メソッドと同じです。ディレクトリパスに解決されるような引数を渡した場合、そのディレクトリ以下の全て（ただし、そのディレクトリ自身は除く）が再帰的にターゲットディレクトリにコピーされます。渡した引数がファイルパスに解決された場合は、そのファイルが目的のディレクトリにコピーされます。 もし、引数に渡したパスにファイルがない場合、その引数は無視されます。 引数にタスクを渡した場合、そのタスクの出力ファイル(タスクが作成するファイル)がコピーされ、そのタスクは自動的にCopyタスクが依存しているタスクとして設定されます。 into()メソッドは、file()と同じ型を引数に取ります。以下にもう一つ例を挙げます。

task anotherCopyTask(type: Copy) {
    // Copy everything under src/main/webapp
    from 'src/main/webapp'
    // Copy a single file
    from 'src/staging/index.html'
    // Copy the output of a task
    from copyTask
    // Copy the output of a task using Task outputs explicitly.
    from copyTaskWithPatterns.outputs
    // Copy the contents of a Zip file
    from zipTree('src/main/assets.zip')
    // Determine the destination directory later
    into { getDestDir() }
}

You can select the files to copy using Ant-style include or exclude patterns, or using a closure:

Antスタイルのinclude/excludeパターンかクロージャを用いて、コピーするファイルを選択することができます。

task copyTaskWithPatterns(type: Copy) {
    from 'src/main/webapp'
    into 'build/explodedWar'
    include '**/*.html'
    include '**/*.jsp'
    exclude { details -> details.file.name.endsWith('.html') &&
                         details.file.text.contains('staging') }
}

You can also use the Project.copy() method to copy files. It works the same way as the task with some major limitations though. First, the copy() is not incremental (see 「更新されていないタスクをスキップするSkipping tasks that are up-to-date」).

また、Project.copy()メソッドでファイルをコピーすることもできます。これはタスクの場合と大体同じように動作しますが、いくつかの大きな制限もあります。まず、copy()メソッドはインクリメンタルには実施されません(「更新されていないタスクをスキップするSkipping tasks that are up-to-date」参照)。

task copyMethod << {
    copy {
        from 'src/main/webapp'
        into 'build/explodedWar'
        include '**/*.html'
        include '**/*.jsp'
    }
}

Secondly, the copy() method can not honor task dependencies when a task is used as a copy source (i.e. as an argument to from()) because it's a method and not a task. As such, if you are using the copy() method as part of a task action, you must explicitly declare all inputs and outputs in order to get the correct behavior.

次に、タスクがコピー元として使われる場合(from()メソッドの引数になる場合)でも、copy()メソッドはタスクの依存関係を考慮しません。copy()はあくまでメソッドであってタスクではないからです。 よって、copy()メソッドをタスクアクションの中で呼び出す場合は、正しく動作させるために明示的に全ての入力と出力を宣言する必要があります。

task copyMethodWithExplicitDependencies{
    // up-to-date check for inputs, plus add copyTask as dependency
    inputs.file copyTask
    outputs.dir 'some-dir' // up-to-date check for outputs
    doLast{
        copy {
            // Copy the output of copyTask
            from copyTask
            into 'some-dir'
        }
    }
}

It is preferable to use the Copy task wherever possible, as it supports incremental building and task dependency inference without any extra effort on your part. The copy() method can be used to copy files as part of a task's implementation. That is, the copy method is intended to be used by custom tasks (see 58章カスタムタスクの作成Writing Custom Task Classes) that need to copy files as part of their function. In such a scenario, the custom task should sufficiently declare the inputs/outputs relevant to the copy action.

できるだけCopyタスクのほうを使用するようにしてください。そうすれば、余計な手間をかけずにインクリメンタルビルドやタスク依存関係の恩恵を受けることができます。 一方、copy()メソッドは、あるタスクの実装の一部としてファイルコピーを組み込むことができます。 つまり、copy()メソッドはカスタムタスク(58章カスタムタスクの作成Writing Custom Task Classes参照)の機能でファイルコピーが必要になった場合に使用されることを想定しています。 そのカスタムタスクでは、ファイルコピーの実際の仕様に基づいて適切に入力と出力が宣言されていなければなりません。

task rename(type: Copy) {
    from 'src/main/webapp'
    into 'build/explodedWar'
    // Use a closure to map the file name
    rename { String fileName ->
        fileName.replace('-staging-', '')
    }
    // Use a regular expression to map the file name
    rename '(.+)-staging-(.+)', '$1$2'
    rename(/(.+)-staging-(.+)/, '$1$2')
}

import org.apache.tools.ant.filters.FixCrLfFilter
import org.apache.tools.ant.filters.ReplaceTokens

task filter(type: Copy) {
    from 'src/main/webapp'
    into 'build/explodedWar'
    // Substitute property tokens in files
    expand(copyright: '2009', version: '2.3.1')
    expand(project.properties)
    // Use some of the filters provided by Ant
    filter(FixCrLfFilter)
    filter(ReplaceTokens, tokens: [copyright: '2009', version: '2.3.1'])
    // Use a closure to filter each line
    filter { String line ->
        "[$line]"
    }
}

task nestedSpecs(type: Copy) {
    into 'build/explodedWar'
    exclude '**/*staging*'
    from('src/dist') {
        include '**/*.html'
    }
    into('libs') {
        from configurations.runtime
    }
}

The Sync task extends the Copy task. When it executes, it copies the source files into the destination directory, and then removes any files from the destination directory which it did not copy. This can be useful for doing things such as installing your application, creating an exploded copy of your archives, or maintaining a copy of the project's dependencies.

SyncはCopyタスクを継承したタスクです。このタスクは、宛先ディレクトリにファイルをコピーし、その後、コピーしたファイル以外の全ファイルを宛先ディレクトリから削除します。これは、アプリケーションをインストールしたり、アーカイブを解凍したり、プロジェクトの依存関係のコピーをメンテナンスしたりするのに便利です。

Here is an example which maintains a copy of the project's runtime dependencies in the build/libs directory.

次の例では、build/libsにある実行時依存関係のコピーをメンテナンスしています。

task libs(type: Sync) {
    from configurations.runtime
    into "$buildDir/libs"
}

A project can have as many as JAR archives as you want. You can also add WAR, ZIP and TAR archives to your project. Archives are created using the various archive tasks: Zip, Tar, Jar, War, and Ear. They all work the same way, so let's look at how you create a ZIP file.

一つのプロジェクトで、JARファイルを好きなだけ作成することができます。WAR、ZIP、TARなどのアーカイブをプロジェクトに加えることもできます。 アーカイブは、 Zip、 Tar、 Jar、 War、 Earなどのアーカイブタスクを使って作成します。 これらは全て同じ使い方なので、ここではZIPファイルの作成方法を見てみましょう。

apply plugin: 'java'

task zip(type: Zip) {
    from 'src/dist'
    into('libs') {
        from configurations.runtime
    }
}

The archive tasks all work exactly the same way as the Copy task, and implement the same CopySpec interface. As with the Copy task, you specify the input files using the from() method, and can optionally specify where they end up in the archive using the into() method. You can filter the contents of file, rename files, and all the other things you can do with a copy spec.