第16章 Working With Files 跟文件工作 · Gradle 2 用戶指南

大多數構建工作都要使用到文件。Gradle 添加了一些概念和 API 來幫助您實現這一目標。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#161-locating-files-定位文件)16.1\. Locating files 定位文件使用?[Project.file()](http://gradle.org/docs/current/dsl/org.gradle.api.Project.html#org.gradle.api.Project:file(java.lang.Object))?方法來定位相對于 project 目錄相關的文件。 Example 16.1\. Locating files build.gradle ~~~ // 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')) ~~~ 您可以把任何對象傳遞給 file() 方法，而它將嘗試將其轉換為一個絕對路徑的 File 對象。通常情況下，你會傳給它一個 String 或 File 的實例。如果這個路徑是一個絕對路徑，它會用于構構一個 File 實例。否則，會通過先計算所提供的路徑相對于項目目錄的相對路徑來構造 File 實例。這個 file() 方法也可以識別 URL，例如是 file:/some/path.xml。這是把一些用戶提供的值轉換為一個相對路徑的 File 對象的有用方法。由于 file() 方法總是去計算所提供的路徑相對于項目目錄的路徑，最好是使用 new File(somePath)，因為它是一個固定的路徑，而不會因為用戶運行 Gradle 的具體工作目錄而改變。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#162-file-collections-文件集合)16.2\. File collections 文件集合一個文件集合簡單的說就是一組文件。它通過?[FileCollection](http://gradle.org/docs/current/javadoc/org/gradle/api/file/FileCollection.html)?接口來表示。Gradle API 中的許多對象都實現了此接口。比如，[15.3 依賴配置](http://gradle.org/docs/current/userguide/dependency_management.html#sub:configurations)章節就實現了 FileCollection 這一接口。使用?[Project.files()](http://gradle.org/docs/current/dsl/org.gradle.api.Project.html#org.gradle.api.Project:files(java.lang.Object%5B%5D))?方法是獲取一個 FileCollection 實例的其中一個方法。你可以向這個方法傳入任意個對象，而它們會被轉換為一組 File 對象。這個 files() 方法接受任何類型的對象作為其參數。根據[16.1 章節 “定位文件”](http://gradle.org/docs/current/userguide/working_with_files.html#sec:locating_files)里對 file() 方法的描述，它的結果會被計算為相對于項目目錄的相對路徑。你也可以將集合，迭代變量，map 和數組傳遞給 files() 方法。它們會被展開，并且內容會轉換為 File 實例。 Example 16.2\. Creating a file collection build.gradle ~~~ FileCollection collection = files('src/file1.txt', new File('src/file2.txt'), ['src/file3.txt', 'src/file4.txt']) ~~~ 一個文件集合是可迭代的，并且可以使用 as 操作符轉換為其他類型的對象集合。您還可以使用 + 運算符把兩個文件集合相加，或使用 - 運算符減去一個文件集合。這里是一些使用文件集合的例子 Example 16.3\. Using a file collection build.gradle ~~~ // 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') ~~~ 你也可以向 files() 方法傳一個閉包或一個 Callable 實例。它會在查詢集合內容，并且它的返回值被轉換為一組文件實例時被調用。這個閉包或Callable 實例的返回值可以是 files() 方法所支持的任何類型的對象。這是 “實現” FileCollection 接口的簡單方法。 Example 16.4\. Implementing a file collection build.gradle ~~~ 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 ~~~ > gradle -q list Contents of src src/dir1 src/file1.txt Contents of src2 src2/dir1 src2/dir2 ~~~ 你可以向 files() 傳入一些其他類型的對象： **FileCollection** 它們會被展開，并且內容會被包含在文件集合內。 **Task** 任務的輸出文件會被包含在文件集合內。 **TaskOutputs** TaskOutputs 的輸出文件會被包含在文件集合內。要注意的一個地方是，一個文件集合的內容是緩計算的，它只在需要的時候才計算。這意味著您可以，比如創建一個 FileCollection 對象而里面的文件會在以后才創建，比方說在一些任務中才創建。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#163-file-trees-文件樹)16.3\. File trees 文件樹文件樹是按層次結構排序的文件集合。例如，文件樹可能表示一個目錄樹或 ZIP 文件的內容。它通過 FileTree 接口表示。FileTree 接口繼承自FileCollection，所以你可以用對待文件集合一樣的方式來對待文件樹。Gradle 中的幾個對象都實現了 FileTree 接口，例如 source sets。使用 Project.fileTree() 方法是獲取一個 FileTree 實例的其中一種方法。它將定義一個基目錄創建 FileTree 對象，并可以選擇加上一些 Ant 風格的包含與排除模式 Example 16.5\. Creating a file tree build.gradle ~~~ // 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*/**') ~~~ 你可以像使用一個文件集合的方式一樣來使用一個文件樹。你也可以使用 Ant 風格的模式來訪問文件樹的內容或選擇一個子樹： Example 16.6\. Using a file tree build.gradle ~~~ // 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" } ~~~ ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#164-using-the-contents-of-an-archive-as-a-file-tree-使用歸檔文件的內容作為文件樹)16.4\. Using the contents of an archive as a file tree 使用歸檔文件的內容作為文件樹您可以使用檔案的內容，如 ZIP 或者 TAR 文件，作為一個文件樹。你可以通過使用 Project.zipTree() 或 Project.tarTree() 方法來實現這一過程。這些方法返回一個 FileTree 實例，您可以像使用任何其他文件樹或文件集合一樣使用它。例如，您可以用它來通過復制內容擴大歸檔，或把一些檔案合并到另一個歸檔文件中。 Example 16.7\. Using an archive as a file tree build.gradle ~~~ // 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')) ~~~ ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#165-specifying-a-set-of-input-files-指定一組輸入文件)16.5\. Specifying a set of input files 指定一組輸入文件 Gradle 中的許多對象都有一個接受一組輸入文件的屬性。例如， JavaCompile 任務有一個 source 屬性，定義了要編譯的源代碼文件。你可以使用上面所示的 files() 方法所支持的任意類型的對象設置此屬性。這意味著您可以通過如 File、String、集合、 FileCollection對象，或甚至是一個閉包來設置此屬性。這里有一些例子： Example 16.8\. Specifying a set of files build.gradle ~~~ // 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) } } } ~~~ 通常情況下，有一個與屬性相同名稱的方法，可以追加這個文件集合。再者，這個方法接受 files() 方法所支持的任何類型的參數。 Example 16.9\. Specifying a set of files build.gradle ~~~ 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() } } ~~~ ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#166-copying-files-拷貝文件)16.6\. Copying files 拷貝文件你可以使用 Copy 任務來復制文件。復制任務非常靈活，并允許您進行，比如篩選要復制的文件的內容，或映射文件的名稱。若要使用 Copy 任務，您必須提供用于復制的源文件和目標目錄。您還可以在復制文件的時候指定如何轉換文件。你可以使用一個復制規范來做這些。一個復制規范通過 CopySpec 接口來表示。Copy 任務實現了此接口。你可以使用 CopySpec.from() 方法指定源文件，使用 CopySpec.into() 方法使用目標目錄。 Example 16.10\. Copying files using the copy task build.gradle ~~~ task copyTask(type: Copy) { from 'src/main/webapp' into 'build/explodedWar' } ~~~ from() 方法接受和 files() 方法一樣的任何參數。當參數解析為一個目錄時，該目錄下的所有文件（不包含目錄本身）都會遞歸復制到目標目錄。當參數解析為一個文件時，該文件會復制到目標目錄中。當參數解析為一個不存在的文件時，參數會被忽略。如果參數是一個任務，那么任務的輸出文件（即該任務創建的文件）會被復制，并且該任務會自動添加為Copy任務的依賴項。 into() 方法接受和 files() 方法一樣的任何參數。這里是另一個示例： Example 16.11\. Specifying copy task source files and destination directory build.gradle ~~~ 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() } } ~~~ 您可以使用 Ant 風格的包含或排除模式，或使用一個閉包，來選擇要復制的文件： Example 16.12\. Selecting the files to copy build.gradle ~~~ 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') } } ~~~ 此外，你也可以使用 Project.copy() 方法來復制文件。它是與任務一樣的工作方式，盡管它有一些主要的限制。首先， copy() 不能進行增量操作（見[15.9章節，"跳過處于最新狀態的任務"](http://gradle.org/docs/current/userguide/more_about_tasks.html#sec:up_to_date_checks)）。 Example 16.13\. Copying files using the copy() method without up-to-date check build.gradle ~~~ task copyMethod << { copy { from 'src/main/webapp' into 'build/explodedWar' include '**/*.html' include '**/*.jsp' } } ~~~ 第二，當一個任務用作復制源（即作為 from() 的參數）的時候，copy()方法不能建立任務依賴性，因為它是一個方法，而不是一個任務。因此，如果您在任務的 action 里面使用 copy() 方法，必須顯式聲明所有的輸入和輸出以得到正確的行為。 Example 16.14\. Copying files using the copy() method with up-to-date check build.gradle ~~~ 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' } } } ~~~ 在可能的情況下，最好是使用 Copy 任務，因為它支持增量構建和任務依賴關系推理，而不需要你額外付出。copy() 方法可以作為一個任務執行的部分來復制文件。即，這個 copy() 方法旨在用于自定義任務（見[Chapter 58\. Writing Custom Task Classes 編寫自定義任務類](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2058.%20Writing%20Custom%20Task%20Classes%20%E7%BC%96%E5%86%99%E8%87%AA%E5%AE%9A%E4%B9%89%E4%BB%BB%E5%8A%A1%E7%B1%BB.md)）中，需要文件復制作為其一部分功能的時候。在這種情況下，自定義任務應充分聲明與復制操作有關的輸入/輸出。 ### [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#1661-renaming-files-重命名)16.6.1\. Renaming files 重命名 Example 16.15\. Renaming files as they are copied build.gradle ~~~ 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') } ~~~ ### [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#1662-filtering-files-過濾文件)16.6.2\. Filtering files 過濾文件 Example 16.16\. Filtering files as they are copied build.gradle ~~~ 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]" } } ~~~ 在源文件中，“expand” 和 “filter” 操作查找的 “token” ，被格式化成“@tokenName@” （名稱是 “tokenName”） ### [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#1663-using-the-copyspec-class--使用copyspec類)16.6.3\. Using the CopySpec class 使用CopySpec類復制規范用來組織一個層次結構。一個復制規范繼承其目標路徑，包含模式，排除模式，復制操作，名稱映射和過濾器。 Example 16.17\. Nested copy specs build.gradle ~~~ task nestedSpecs(type: Copy) { into 'build/explodedWar' exclude '**/*staging*' from('src/dist') { include '**/*.html' } into('libs') { from configurations.runtime } } ~~~ ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#167-using-the-sync-task-使用sync任務)16.7\. Using the Sync task 使用Sync任務 Sync 任務繼承了 Copy 任務。當它執行時，它會將源文件復制到目標目錄中，然后從目標目錄移除所有不是它復制的文件。這可以用來做一些事情，比如安裝你的應用程序、創建你的歸檔文件的 exploded 副本，或維護項目的依賴項的副本。這里是一個例子，維護在 build/libs 目錄中的項目運行時依賴的副本。 Example 16.18\. Using the Sync task to copy dependencies build.gradle ~~~ task libs(type: Sync) { from configurations.runtime into "$buildDir/libs" } ~~~ ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#168-creating-archives-創建歸檔文件)16.8\. Creating archives 創建歸檔文件一個項目可以有你所想要的一樣多的 JAR 文件。您也可以將 WAR、 ZIP 和TAG 文件添加到您的項目。使用各種歸檔任務可以創建以下的歸檔文件： Zip, Tar, Jar, War, and Ear. 他們的工作方式都一樣，所以讓我們看看如何創建一個 ZIP 文件。 Example 16.19\. Creating a ZIP archive build.gradle ~~~ apply plugin: 'java' task zip(type: Zip) { from 'src/dist' into('libs') { from configurations.runtime } } ~~~ 歸檔任務與 Copy 任務的工作方式一樣，并且實現了相同的 CopySpec 接口。像使用 Copy 任務一樣，你需要使用 from() 的方法指定輸入的文件，并可以選擇是否通過 into() 方法指定最終在存檔中的位置。您可以通過一個復制規范來篩選文件的內容、重命名文件和進行其他你可以做的事情。 ### [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#1681-archive-naming)16.8.1\. Archive naming 生成的歸檔的默認名稱是 projectName-version.type。舉個例子： Example 16.20\. Creation of ZIP archive build.gradle ~~~ 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 ~~~ > gradle -q myZip zipProject-1.0.zip build/distributions build/distributions/zipProject-1.0.zip ~~~ 它添加了一個名稱為 myZip 的 ZIP 歸檔任務，產生 ZIP 文件 zipProject 1.0.zip 。區分歸檔任務的名稱和歸檔任務生成的歸檔文件的名稱是很重要的。歸檔的默認名稱可以通過項目屬性 archivesBaseName 來更改。還可以在以后的任何時候更改歸檔文件的名稱。這里有很多你可以在歸檔任務中設置的屬性。它們在以下的[表 16.1，"存檔任務-命名屬性"](http://gradle.org/docs/current/userguide/working_with_files.html#archiveTasksNamingProperties)中列出。你可以，比方說，更改歸檔文件的名稱： Example 16.21\. Configuration of archive task - custom archive name build.gradle ~~~ apply plugin: 'java' version = 1.0 task myZip(type: Zip) { from 'somedir' baseName = 'customName' } println myZip.archiveName ~~~ 執行 gradle -q myZip ~~~ > gradle -q myZip customName-1.0.zip ~~~ 您可以進一步自定義存檔名稱： Example 16.22\. Configuration of archive task - appendix & classifier build.gradle ~~~ 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 -q myZip gradle-wrapper-1.0-src.zip ~~~ Table 16.1\. Archive tasks - naming properties | 屬性名稱 | 類型 | 默認值 | 描述 | | --- | --- | --- | --- | | `archiveName` | `String` | baseName-appendix-version-classifier.extension 如果這些屬性中的任何一個為空，那后面的-不會被添加到該名稱中。 | 生成的歸檔文件的基本文件名 | | `archivePath` | `File` | `destinationDir/archiveName` | 生成的歸檔文件的絕對路徑。 | | `destinationDir` | `File` | 依賴于歸檔類型。JAR包和 WAR包會生成到 project.buildDir/libraries中。ZIP文件和 TAR文件會生成到project.buildDir/distributions中。 | 存放生成的歸檔文件的目錄 | | `baseName` | `String` | `*`project.name`*` | 歸檔文件的名稱中的基本名稱部分。 | | `appendix` | `String` | `null` | 歸檔文件的名稱中的附錄部分 | | `version` | `String` | `*`project.version`*` | 歸檔文件的名稱中的版本部分。 | | `classifier` | `String` | `null` | 歸檔文件的名稱中的分類部分。 | | `extension` | `String` | 依賴于歸檔的類型，用于TAR文件，可以是以下壓縮類型： zip, jar, war, tar, tgz or tbz2. | 歸檔文件的名稱中的擴展名稱部分。 | ### [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2016.%20Working%20With%20Files%20%E8%B7%9F%E6%96%87%E4%BB%B6%E5%B7%A5%E4%BD%9C.md#1682-sharing-content-between-multiple-archives-共享多個歸檔之間的內容)16.8.2\. Sharing content between multiple archives 共享多個歸檔之間的內容你可以使用[Project.copySpec()](http://gradle.org/docs/current/dsl/org.gradle.api.Project.html#org.gradle.api.Project:copySpec(groovy.lang.Closure))方法在歸檔之間共享內容。你經常會想要發布一個歸檔文件，這樣就可從另一個項目中使用它。這一過程在[Chapter 52\. Publishing artifacts 發布 artifact](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2052.%20Publishing%20artifacts%20%E5%8F%91%E5%B8%83%20artifact.md)會講到