目錄

• 1 介紹
  • 1.1 新構建系統的目標
  • 1.2 Gradle是什麼?
• 2 要求
• 3 基礎工程
  • 3.1 基本的build檔案
  • 3.2 工程結構
    • 3.2.1 配置結構
  • 3.3 構建任務
    • 3.3.1 通用任務
    • 3.3.2 Java工程任務
    • 3.3.3 Android任務
  • 3.4 自定義構建
    • 3.4.1 Manifest選項
    • 3.4.2 構建型別
    • 3.4.3 簽名配置
    • 3.4.4 使用混淆
    • 3.4.5 清理資源
• 4 依賴，Android庫工程以及多工程設定
  • 4.1 依賴二進位制包
    • 4.1.1 本地包
    • 4.1.2 遠端artifacts
  • 4.2 多工程設定
  • 4.3 庫工程
    • 4.3.1 建立一個庫工程
    • 4.3.2 普通工程和庫工程的區別
    • 4.3.3 引用一個庫工程
    • 4.3.4 庫工程釋出
• 5 測試
  • 5.1 基本介紹以及配置
  • 5.2 執行測試
  • 5.3 測試Android庫
  • 5.4 測試報告
    • 5.4.1 單工程報告
    • 5.4.2 多工程報告
  • 5.5 Lint支援
• 6 Build Variants(構建變種版本)
  • 6.1 Product flavors(產品定製)
  • 6.2 Build Type(構建型別) + Product Flavor(產品定製) = Build Variant(構建變種版本)
  • 6.3 Product Flavor Configuration(產品定製配置)
  • 6.4 Sourcesets and Dependencies(Sourcesets和依賴)
  • 6.5 Building and Tasks(構建和任務)
  • 6.6 Testing(測試)
  • 6.7 Multi-flavor variants(多種定製的版本)
• 7 高階構建定製
  • 7.1 構建選項
    • 7.1.1 Java編譯選項
    • 7.1.2 aapt選項
    • 7.1.3 dex選項
  • 7.2 操縱任務
  • 7.3 BuildType and Product Flavor的屬性參考
  • 7.4 使用sourceCompatibility 1.7

1 介紹

本文件適用於Gradle plugin 0.9版本，所以可能和我們1.0之前介紹的老版本有所不同。

1.1 新構建系統的目標

新構建系統的目標是：

• 可以很容易的重用程式碼和資源
• 可以很容易的建立應用的衍生版本，所以不管你是建立多個apk，還是不同功能的應用都很方便
• 可以很容易的配置、擴充套件以及自定義構建過程
• 和IDE無縫整合

1.2 Gradle是什麼

Gradle是一個非常優秀的構建系統工具，允許你通過外掛的方式建立自定義的構建邏輯

Gradle的以下特性讓我們選擇了它：

• 用過領域專用語言(DSL)描述和控制構建邏輯
• 構建檔案基於Groovy，並且可以組合使用各種定義的元素，然後通過程式碼來控制這些DSL達到定製邏輯的目的
• 內建的基於Maven或者Ivy的依賴管理
• 使用非常靈活，Gradle不會強制實現的方式，你可以使用最佳實踐
• 外掛能提供DSL以及API為構建檔案使用
• 良好的工具API以供IDE整合

2 要求

• Gradle 1.10或者1.11或者1.12，並且使用0.11.1版本的外掛
• SDK with Build Tools要求19.0.0，有些功能可能需要更新的版本

3 基礎工程

一個Gradle工程是通過名字叫 build.gradle 的檔案描述其構建過程的，該文字位於工程的根目錄下。

3.1 基本的build檔案

最基本的Java工程，其 build.gradle 非常簡單：

apply plugin: 'java'

這裡應用了Gradle提供的Java外掛。該外掛提供了構建和測試Java應用所需的一些東西。

一個最基本的Android工程的build.gradle如下：

buildscript {
    repositories {
        mavenCentral()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:0.11.1'
    }
}

apply plugin: 'android'

android {
    compileSdkVersion 19
    buildToolsVersion "19.0.0"
}

在Android buid file中，有3個主要組成部分。

buildscript { ... }部分配置了驅動構建的程式碼。

在該部分中，定義配置使用了Maven中央倉庫，並且宣告依賴一個Maven artifact(構件？)。 這個artifact是一個包含0.11.1版本的Android Gradle外掛庫。

注意： 這部分的配置只會影響構建過程的程式碼，和你的工程沒有關係。工程會定義它自己的倉庫和相關依賴。稍候會詳細介紹。

接下來，android外掛被應用，這和上面的Java外掛是一樣的。

最後，android { ... }這部分配置了android構建需要的所有引數。這裡也是Android DSL的入口點。

預設情況下，只有編譯的目標SDK、構建工具的版本是必需的。就是compileSdkVersion和buildtoolsVersion兩個配置屬性。

compilation target和舊構建系統中的project.properties檔案裡 target 屬性是一樣的。這個新的屬性和以前的 target 一樣，可以指定一個int型別(api級別)或者string類的值。

重要: 你應該只應用android外掛就好了，不要同時應用java外掛，因為這會導致構建錯誤

注意： 你還需要在同目錄下新增一個 local.properties 檔案，並通過sdk.dir屬性配置所需的SDK的路徑。除此之外，你也可以設定一個名為ANDROID_HOME環境變數。這兩種方法都差不多，你可以選擇自己喜歡的。

3.2 工程結構

上面說的build檔案約定了一個預設的資料夾結構。Gradle遵循約定優先於配置的原則，在可能的情況下提供合理的預設值。

基本的工程始於兩個名為"source sets"的部分。也就是main source code 和 test code。他們分別位於：

• src/main
• src/androidTest/

裡面的每一個資料夾都對應相應的元件。

對於Java和Android這兩個外掛來說，他們的Java原始碼和Java資源的位置是：

• java/
• resources/

對於Android外掛來說，它還有以下特性檔案和資料夾：

• AndroidManifest.xml
• res/
• assets/
• aidl/
• rs/
• jni/

注意： src/androidTest/AndroidManifest.xml是不需要的，它會被自動建立。

3.2.1 配置結構

當預設的工程結構不適用的時候，你可能需要配置它。根據Gradle文件說明，可以通過如下方式重新配置Java工程的sourceSets:

sourceSets {
    main {
        java {
            srcDir 'src/java'
        }
        resources {
            srcDir 'src/resources'
        }
    }
}

注意： srcDir會新增指定的資料夾到現有的原始檔夾列表中(Gradle文件沒有提到這個，但是的確是這樣)。

要替換預設的原始檔夾的話，可以給srcDirs指定一個路徑陣列 。下面使用物件呼叫另一種方式配置：

sourceSets {
    main.java.srcDirs = ['src/java']
    main.resources.srcDirs = ['src/resources']
}

想要了解更多的資訊，請參考Gradle文件的Java外掛部分。

Android外掛也使用相似的語法，但是它有它自己的 sourceSets ,這些已經內建在android物件中了。

這兒有個示例，它使用了舊工程結構的原始碼，並且重新映射了androidTest sourceSet 到測試資料夾：

android {
    sourceSets {
        main {
            manifest.srcFile 'AndroidManifest.xml'
            java.srcDirs = ['src']
            resources.srcDirs = ['src']
            aidl.srcDirs = ['src']
            renderscript.srcDirs = ['src']
            res.srcDirs = ['res']
            assets.srcDirs = ['assets']
        }

        androidTest.setRoot('tests')
    }
}

注意： 因為舊結構中把所有的原始檔(java, aidl, renderscript, and java resources)都放在同一資料夾下，所以我們需要重新對映這些 sourceSet 的新元件到同一src目錄.

注意: setRoot()方法會移動整個 sourceSet (包括其下的子資料夾)到一個新資料夾。這裡是移動src/androidTest/*到tests/*。

這些都是Android特有的，並不適用於Java sourceSets 。

這是一個遷移的例子(譯者注：比如從舊工程結構遷移過來)。

3.3 構建任務

3.3.1 通用任務

在構建檔案中應用一個外掛的時候會自動的建立一系列可執行的構建任務。Java plugin 和 the Android plugin都可以做到這一點。以下是約定的一些任務：

• assemble 這個任務會彙集工程的所有輸出。
• check 這個任務會執行所有校驗檢查
• build 這個任務會同時執行 assemble 和 check 任務
• clean 這個任務會清理工程的所有輸出

事實上， assemble , check 以及 build 這三個任務並沒有作任何事情，他們只是外掛的引導任務，引導外掛新增的其他任務去完成一些工作。

這樣就可以允許你呼叫同樣的任務，而不用管它是什麼型別的工程或者應用了什麼外掛。

比如，應用 findbugs 外掛會建立一個任務，並且讓 check 任務依賴它，這樣當這個 check 任務被呼叫的時候，這個新建立的任務也會被呼叫.

在命令列中輸入如下命令可以獲取一些高級別的任務介紹。

gradle tasks

要檢視所有的任務列表以及任務之間的依賴關係執行：

gradle tasks --all

注意： Gradle會自動監控任務定義的輸入和輸出。

不做任何改變兩次執行 build ，Gradle會報告所有任務已經處於UP-TO-DATE狀態，這意味著沒有什麼可做的。這使得任務之間可以正確的相互依賴，又不會導致其他不需要的操作執行。

3.3.2 Java工程任務

Java plugin建立了兩個主要的任務，主要的引導任務都依賴他們。

• assemble
  • jar 這個任務建立所有輸出
• check
  • test 這個任務執行所有測試

jar 任務直接或者間接的依賴其他任務：比如 classes 會編譯所有Java程式碼.

testClasses 會編譯所有測試，但是它很少使用，因為 test這個任務依賴它(和 classes 差不多)。

通常情況下，你可能只用到 assemble 或者 check ,其他的任務不會使用。

你可以在這兒看到Java plugin的所有任務列表以及他們的依賴關係

3.3.3 Android任務

Android plugin使用了同樣的約定規則以和其他外掛保持相容，並且又添加了一些額外的引導任務:

• assemble 這個任務會彙集工程的所有輸出。
• check 這個任務會執行所有校驗檢查
• connectedCheck 執行checks需要一個連線的裝置或者模擬器，這些checks將會同時執行在所有連線的裝置上。
• deviceCheck 通過API連線遠端裝置執行checks。它被用於CI(譯者注:持續整合)伺服器上。
• build 這個任務會同時執行 assemble 和 check 任務
• clean 這個任務會清理工程的所有輸出

這些新的引導任務是必須的，以便能夠在沒有連線的裝置的情況下執行定期檢查。

注意 build 既不依賴 deviceCheck ,也不依賴 connectedCheck 。

一個Android工程至少有兩個輸出:一個debug APK和一個release APK。他們每一個都有自己的引導任務以便可以單獨的構建他們：

• assemble
  • assembleDebug
  • assembleRelease

他們兩個都依賴其他任務，這些任務執行很多必須的步驟以生成一個APK。 assemble 任務又依賴他們兩個，所以執行 assemble 會生成兩個APK。

提示：在命令列下，Gradle支援任務名稱駝峰方式的快捷呼叫，比如：

gradle aR

和

gradle assembleRelease

是一樣的，當然前提是沒有其他任務匹配'aR'。

檢驗引導任務也有他們自己的依賴：

• check
  • lint
• connectedCheck
  • connectedAndroidTest
  • connectedUiAutomatorTest (尚未實現)
• deviceCheck
  • 這個依賴其他外掛建立的時候實現的測試擴充套件點的哪些任務。

最後，外掛會為所有的構建型別( debug, release, test )建立install/uninstall任務，也只有他們能被安裝（需要簽名）。

3.4 自定義構建

Android plugin提供了大量的DSL能夠讓你直接基於構建系統定製很多事情。

3.4.1 Manifest選項

通過DSL可以配置manifest的如下選項：

• minSdkVersion
• targetSdkVersion
• versionCode
• versionName
• applicationId (更有效的packageName -- 請看ApplicationId 與 PackageName獲取更多資訊)
• Package Name for the test application
• Instrumentation test runner

示例:

android {
    compileSdkVersion 19
    buildToolsVersion "19.0.0"

    defaultConfig {
        versionCode 12
        versionName "2.0"
        minSdkVersion 16
        targetSdkVersion 16
    }
}

android 元素裡的 defaultConfig 負責定義所有的配置。

Android Plugin以前的版本是使用packageName配置manifest的'packageName'屬性。從0.11.0開始，你應該在build.gradle裡使用applicationId來配置manifest的'packageName'屬性。這是為了消除應用的packageName（也就是ID）和java的packages之間的歧義。

通過build檔案定義的強大之處在於可以動態的被配置。比如，可以從一個檔案讀取版本名字，或者使用一些其他的自定義的邏輯：

def computeVersionName() {
    ...
}

android {
    compileSdkVersion 19
    buildToolsVersion "19.0.0"

    defaultConfig {
        versionCode 12
        versionName computeVersionName()
        minSdkVersion 16
        targetSdkVersion 16
    }
}

注意： 不要使用在給定的範圍內，和其他已經存在的getters方法衝突的方法名字。比如在defaultConfig { ...}中呼叫getVersionName()方法會自動的呼叫defaultConfig.getVersionName()方法，如果你也自定義一個這樣的名字的方法，那麼你的方法不會呼叫。

如果一個屬性沒有通過DSL設定，則會使用它們的預設值。這裡有個表格說明是如何處理的。

如果你在構建指令碼中使用自定義的邏輯獲取這些屬性的時候，那麼第二列的值尤其重要。比如，你可能這樣寫：

if (android.defaultConfig.testInstrumentationRunner == null) { // assign a better default... }

如果值一直為null，那麼在構建的時候，它將會被從第三列中獲取的實際的預設值替換，但是在DSL元素中又不包含這個預設值，所以你無法查詢到它。這是為了防止解析應用的manifest檔案，除非真的需要。

3.4.2 構建型別

預設情況下，Android plugin會自動的設定工程，構建release和debug兩個版本。他們主要的差異主要在於是否可以在裝置上除錯應用以及APK如何簽名。

debug版本會被使用已知的名稱/密碼自動生成的金鑰/證書籤名。release版本在構建過程中不會被簽名，需要構建後再簽名。

這些配置可以通過一個叫 BuildType 配置。預設情況下，已經建立了 debug 和 release 這兩個例項。

Android plugin允許自定義這兩個示例，並且可以建立其他的 Build Types 。這些是可以在 buildTypes DSL容器中配置完成:

android {
    buildTypes {
        debug {
            applicationIdSuffix ".debug"
        }

        jnidebug.initWith(buildTypes.debug)
        jnidebug {
            packageNameSuffix ".jnidebug"
            jniDebuggable true
        }
    }
}

以上的片段實現了以下幾點：

• 配置了預設的 debug 構建型別：
  • 設定包名為.debug以便可以在同一裝置上同時安裝 debug 和 release 兩個版本的APK
• 建立一個叫 jnidebug 新的 Build Types ，並且配置它作為 debug 構建型別的一個副本
• 然後再配置 jnidebug ，啟用JNI元件的debug構建，並且新增一個不同的包名字尾

建立一個新的 Build Types 很簡單，只需要在 buildTypes 容器下新增一個元素，然後呼叫 initWith() 或者使用一個閉包配置它。

這裡有一些可能用到的屬性以及他們的預設值：

除了這些屬性外， 程式碼和資源也會影響到 Build Types 。對於每一個 Build Type,都會建立一個新的匹配的 sourceSet ，預設位置是

src/<buildtypename>/

這意味著 Build Type 的名字不能是 main 和 androidTest (這兩個已經被外掛佔用)，並且他們相互之間的名字必須唯一。

和其他的source sets一樣，Build Type的source set的位置可以被重定向：

android {
    sourceSets.jnidebug.setRoot('foo/jnidebug')
}

此外，對於每一個 Build Type ，都會新建立assemble<BuildTypeName>任務。

assembleDebug 和 assembleRelease 這兩個任務已經講過了，這裡講的是他們是從哪來的。是在 debug 和 release 這兩個 Build Types 被預先建立的時候。

提示：記得你可以通過輸入gradle aJ來執行assembleJnidebug任務哦。

可能使用到的情況：

• 在debug模式下需要，但是在release下不需要的許可權
• 自定義debug的實現
• 微debug預設使用不同的資源（比如一個資源的值是由簽名的證書決定的）

BuildType 的程式碼/資源主要通過以下方式使用：

• manifest被合併進app的manifest
• 程式碼僅僅是作為一個額外的source資料夾(譯者注：其實和自己新建一個source資料夾，然後在這個資料夾下新建包和類一樣)
• 資源會覆蓋main裡的資源，替換現有的值

3.4.3 簽名配置

要對一個應用簽名，要求如下：

• 一個keystore
• 一個keystore的密碼
• 一個key的別名
• 一個key的密碼
• 儲存型別

位置、key別名、key密碼以及儲存型別一起組成了簽名配置( SigningConfig 型別)

預設情況下， 已經有了一個 debug 的簽名配置，它使用了debug keystore，該keystore有一個已知的密碼和預設的帶有已知密碼的key。 debug keystore位於$HOME/.android/debug.keystore，如果沒有會被建立。

debug Build Type 被設定為自動使用 debug 簽名配置。

你也可以建立其他的簽名配置或者自定義內建的配置。可以通過 signingConfigs DSL容器實現。

android {
    signingConfigs {
        debug {
            storeFile file("debug.keystore")
        }

        myConfig {ss
            storeFile file("other.keystore")
            storePassword "android"
            keyAlias "androiddebugkey"
            keyPassword "android"
        }
    }

    buildTypes {
        foo {
            debuggable true
            jniDebuggable true
            signingConfig signingConfigs.myConfig
        }
    }
}

以上片段會把debug keystore的路徑改為工程的根目錄。這會自動的影響任何用到它的 Build Types ，在這裡影響到的是 debug Build Type 。

以前片段也建立了一個新的簽名配置，並且被一個新的 Build Type 使用。

注意： 只有預設路徑下的debug keystores才會被自動建立。如果改變了debug keystore的路徑將不會在需要的時候建立。建立一個使用不同名字的 SigningConfig ，但是用的是預設的debug keystore路徑的話是會被自動建立的。也就是說，會不會被自動建立，和keystore的路徑有關，和配置的名字無關。

說明： 通常情況下，會使用工程根目錄的相對路徑作為keystores的路徑，但有時候也會用絕對路徑，雖然這並不推薦(被自動建立的debug keystore除外)。

注意：如果已經你將這些檔案放到版本控制中，你可能不想把密碼儲存在檔案中。Stack Overflow上有個帖子介紹可以從控制檯或者環境變數中獲取這些密碼等資訊。

我們以後更新這個指南的時候會新增更多的資訊。

3.4.4 使用混淆

自從Gradle plugin for ProGuard 4.10版本以後，Gradle開始支援混淆。如果通過Build Type的 minifyEnabled 屬性配置了使用混淆後，The ProGuard plugin會自動被應用，並且自動建立一些任務。

android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFile getDefaultProguardFile('proguard-android.txt')
        }
    }

    productFlavors {
        flavor1 {
        }
        flavor2 {
            proguardFile 'some-other-rules.txt'
        }
    }
}

使用buildTypes以及productFlavors定義的規則檔案可以輕鬆的生成多種版本。

有兩個預設的規則檔案

• proguard-android.txt
• proguard-android-optimize.txt

他們位於SDK中，使用getDefaultProguardFile()方法可以返回檔案的全路經。除了是否啟用優化之外，這兩個檔案的其他功能都是相同的。

3.4.5 清理資源

在構建的時候，你也可以自動的移除一些未使用的資源。更多資訊，請參考資源清理文件

4 依賴，Android庫工程以及多工程設定

Gradle可以依賴其他的一些元件，這些組建可以是外部二進位制包，也可以是其他Gradle工程。

4.1 依賴二進位制包

4.1.1 本地包

要配置依賴一個外部庫jar包，你可以在 compile 配置裡新增一個依賴。

dependencies {
    compile files('libs/foo.jar')
}

android {
    ...
}

注： dependencies DSL元素是標準Gradle API的一部分，並不屬於 android 的元素。