第16章 ファイルを取り扱う

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章カスタムタスクの作成) 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章カスタムタスクの作成参照)の機能でファイルコピーが必要になった場合に使用されることを想定しています。 そのカスタムタスクでは、ファイルコピーの実際の仕様に基づいて適切に入力と出力が宣言されていなければなりません。

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.

アーカイブタスクは、全てCopyタスクと全く同じように動作します。これらのタスクは、Copyタスク同様、CopySpecインターフェースを実装しています。Copyタスクと同じようにfrom()メソッドで入力ファイルを指定し、必須ではありませんがinto()メソッドで最終的にアーカイブが出力される場所を指定します。ファイルのフィルタリング、リネーム、その他コピー仕様で使える全てのオプションを使うことができます。

apply plugin: 'java'

version = 1.0

task myZip(type: Zip) {
    from 'somedir'
}

println myZip.archiveName
println relativePath(myZip.destinationDir)
println relativePath(myZip.archivePath)

> gradle -q myZip
zipProject-1.0.zip
build/distributions
build/distributions/zipProject-1.0.zip

apply plugin: 'java'
version = 1.0

task myZip(type: Zip) {
    from 'somedir'
    baseName = 'customName'
}

println myZip.archiveName

> gradle -q myZip
customName-1.0.zip

apply plugin: 'java'
archivesBaseName = 'gradle'
version = 1.0

task myZip(type: Zip) {
    appendix = 'wrapper'
    classifier = 'src'
    from 'somedir'
}

println myZip.archiveName

> gradle -q myZip
gradle-wrapper-1.0-src.zip

Often you will want to publish an archive, so that it is usable from another project. This process is described in 52章アーティファクトの公開

アーカイブを別のプロジェクトで使えるようにするために、そのアーカイブを公開したくなることがよくあります。この処理については、52章アーティファクトの公開 に記載されています。