目錄
Gradle Enterprise Gradle插件用戶手冊
附錄D：與Gradle Build Tool和Gradle Enterprise的插件兼容性
Gradle Enterprise Gradle插件用戶手冊
Gradle Enterprise Gradle插件可與Gradle Enterprise和scans.gradle.com集成。
該插件以前曾被命名爲“build scan”插件。隨着Gradle 6.0和該插件的版本3.0的發佈，它已重命名爲“Gradle Enterprise”插件。因此，在討論舊版本時，本文檔在提及插件時會使用術語“build scan”。
該插件以前曾被命名爲“build scan”插件。隨着Gradle 6.0和該插件的版本3.0的發佈，它已重命名爲“Gradle Enterprise”插件。因此，在討論舊版本時，本文檔在提及插件時會使用術語“build scan”。
1.設定
版本3.1.1是最新版本，並且與所有Gradle 5.x和更高版本兼容。如果使用的是Gradle的早期版本，請參閱Gradle 4.x和更早版本。
本節中的說明描述了爲單個Gradle項目應用和配置插件。請參閱集成許多項目，以獲取有關集成環境中構建的所有項目的幫助。
1.1.應用插件
1.1.1.Gradle 6.x及更高版本
此版本的Gradle用com.gradle.enterprise作插件ID。該插件必須應用在構建的設置文件中。
Groovy
settings.gradle
plugins {
id "com.gradle.enterprise" version "3.1.1"
}
Kotlin
settings.gradle.kts
plugins {
id("com.gradle.enterprise").version("3.1.1")
}
插件將gradleEnterprise {} extension添加到用於配置插件的設置腳本，並將buildScan {}extension擴展添加到根項目。均可用於配置插件。
在本文檔的其餘部分中，配置示例buildScan {}在構建腳本中使用擴展名。在所有情況下，都可以通過在gradleEnterprise {}擴展腳本中放置配置來在設置腳本中指定此配置。
Groovy
settings.gradle
plugins {
id "com.gradle.enterprise" version "3.1.1"
}
gradleEnterprise {
buildScan {
// plugin configuration
}
}
Kotlin
settings.gradle.kts
plugins {
id("com.gradle.enterprise").version("3.1.1")
}
gradleEnterprise {
buildScan {
// plugin configuration
}
}
1.1.2.Gradle 5.x
此版本的Gradle用com.gradle.build-scan作插件ID。該插件必須應用於構建的根項目。
Groovy
build.gradle
plugins {
id "com.gradle.build-scan" version "3.1.1"
}
Kotlin
settings.gradle.kts
plugins {
id("com.gradle.build-scan").version("3.1.1")
}
該插件將buildScan {} extension 擴展添加到用於配置插件的根項目中。
1.2.連接到Gradle Enterprise
要連接到Gradle Enterprise實例，必須配置Gradle Enterprise服務器的位置。
Groovy
build.gradle
buildScan {
server = "https://gradle-enterprise.mycompany.com"
}
Kotlin
settings.gradle.kts
buildScan {
server = "https://gradle-enterprise.mycompany.com"
}
1.2.1.允許不受信任的SSL通信
如果您的Gradle Enterprise服務器使用構建的Java運行時不信任的SSL證書，則在未明確允許不信任的服務器的情況下，您將無法發佈構建掃描。
爲此，將allowUntrustedServer選項設置爲true：
Groovy
Disabling SSL certificate checks
buildScan {
allowUntrustedServer = true
}
Kotlin
Disabling SSL certificate checks
buildScan {
allowUntrustedServer = true
}
使用此配置存在安全風險，因爲它使第三方更容易攔截您的構建掃描數據。只有在可以爲服務器配置受信任的證書之前，才應將其用作短期解決方法。
1.3.連接到scans.gradle.com
如果未指定Gradle Enterprise服務器的位置，則構建掃描將發佈到scans.gradle.com。這需要同意服務條款，可以在https://gradle.com/terms-of-service上找到。
您可以通過在構建中添加以下配置來同意服務條款。
Groovy
build.gradle
buildScan {
termsOfServiceUrl = "https://gradle.com/terms-of-service"
termsOfServiceAgree = "yes"
}
Kotlin
build.gradle.kts
buildScan {
termsOfServiceUrl = "https://gradle.com/terms-of-service"
termsOfServiceAgree = "yes"
}
如果您不同意構建中的服務條款，則在每次嘗試發佈到scans.gradle.com時都要交互詢問您。
注意不要在其他人可能會建立的項目中同意服務條款。
注意不要在其他人可能會建立的項目中同意服務條款。1.4.集成您的CI工具
Gradle plugin for Jenkins突出顯示生成生成掃描的任何Gradle構建的構建掃描鏈接。這使得查看CI構建的構建掃描變得更加容易。
TeamCity的構建掃描插件也可以提供一個醒目的鏈接到構建掃描的執行建立。
2.控制何時發佈構建掃描
應用插件後，構建掃描不會自動發佈。下面介紹了可用於控制何時發佈構建掃描的選項。
對於Gradle Enterprise用戶，建議將構建配置爲對每個構建發佈構建掃描。這使Gradle Enterprise可以提供有關組織構建的更多見解。
對於Gradle Enterprise用戶，建議將構建配置爲2.1.按需發佈
您可以將--scan參數添加到任何Gradle構建中以發佈構建掃描。
$ ./gradlew assemble --scan
如果該構建不適用該插件，則Gradle將自動應用該版本發佈時可用的最新版本。
您還可以通過調用buildScanPublishPrevious插件添加的任務來發布最近運行的構建的構建掃描。
$ ./gradlew buildScanPublishPrevious
於任務名稱很長，因此值得使用Gradle的縮寫命令行符號來執行任務：
$ ./gradlew bSPP
2.2.發佈每個版本
爲了發佈每個構建的構建掃描，可以使用publishAlways()指令：
Groovy
發佈每次構建執行的構建掃描
buildScan {
publishAlways()
}
Kotlin
發佈每次構建執行的構建掃描
buildScan {
publishAlways()
}
2.3.根據條件發佈
爲了自動發佈某些版本的版本掃描，可以使用以下指令：
表1.根據條件自動發佈的選項
| Option | Description |
|---|---|
|
|
如果給定條件爲true，則發佈構建掃描，無論構建成功還是失敗。 |
|
|
僅當構建失敗時才發佈構建掃描。 |
|
|
僅在條件滿足true 且構建失敗時才發佈構建掃描。 |
例如，如果您只想從CI系統中發佈構建掃描（通過具有CI環境變量來識別），則可以執行以下操作：
Groovy
將構建掃描限制爲CI構建
buildScan {
publishAlwaysIf(System.getenv("CI"))
}
Kotlin
將構建掃描限制爲CI構建
buildScan {
publishAlwaysIf(!System.getenv("CI").isNullOrEmpty())
}
您可以以相同方式使用其他選項。如果要基於一組條件配置幾件事，則可以改用if條件：
Groovy
build.gradle
buildScan {
if (System.getenv("CI")) {
publishAlways()
tag "CI"
}
}
Kotlin
build.gradle.kts
buildScan {
if (!System.getenv("CI").isNullOrEmpty()) {
publishAlways()
tag("CI")
}
}
3.與Gradle Enterprise進行身份驗證
（插件3.1+，Gradle Enterprise 2019.4+）
可以將Gradle Enterprise安裝配置爲要求對構建掃描發佈進行身份驗證。此外，可以將安裝配置爲僅允許某些用戶發佈構建掃描。
Gradle Enterprise訪問密鑰應與密碼一樣保密。它們用於授權從構建對Gradle Enterprise的訪問。
Gradle Enterprise訪問密鑰應與密碼一樣保密。它們用於授權從構建對Gradle Enterprise的訪問。3.1.自動訪問密鑰配置
配置構建環境以通過Gradle Enterprise進行身份驗證的最簡單方法是使用provisionGradleEnterpriseAccessKey任務。
$ ./gradlew provisionGradleEnterpriseAccessKey
執行後，它將打開您的Web瀏覽器，並要求確認提供新的訪問密鑰。如果您尚未登錄，將要求您首先在瀏覽器中登錄Gradle Enterprise。
確認後，將生成一個新的訪問密鑰，並將其存儲在Gradle用戶主目錄中的enterprise/keys.properties文件中（~/.gradle默認情況下）。
同一服務器上任何現有的訪問密鑰都將在文件中替換，但不會在該服務器上吊銷以供在其他地方使用。要撤消舊的訪問鍵，請登錄Gradle Enterprise並通過頁面右上方的用戶菜單訪問“My settings”。
如果無法在正確的頁面上自動打開瀏覽器，系統將要求您手動打開構建控制檯中提供的鏈接。
如果無法在正確的頁面上自動打開瀏覽器，系統將要求您手動打開構建控制檯中提供的鏈接。3.2.手動訪問密鑰配置
當不適合自動配置時，也可以爲環境手動配置訪問密鑰。
3.2.1.創建訪問密鑰
要創建新的訪問密鑰，請登錄Gradle Enterprise並通過頁面右上方的用戶菜單訪問“My settings”。從那裏，使用“Access keys”部分來生成訪問密鑰。
然後應在構建環境中通過文件或環境變量複製和配置訪問密鑰值。
3.2.2.通過文件
Gradle Enterprise訪問密鑰存儲在Gradle用戶主目錄內（~/.gradle默認情況下），位於enterprise/keys.properties的Java屬性文件中的。屬性名稱是指服務器的主機名（host name），而值是訪問密鑰( access key)。
gradle-enterprise.mycompany.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq
該文件可能包含多個條目。給定主機值的第一個條目將被使用。
3.2.3.通過環境變量
訪問密鑰也可以通過GRADLE_ENTERPRISE_ACCESS_KEY環境變量指定。這通常更適合CI構建環境。
環境變量的值格式爲«server host name»=«access key»。
$ export GRADLE_ENTERPRISE_ACCESS_KEY=gradle-enterprise.mycompany.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq
$ ./gradlew build
指定服務器主機名是爲了防止將訪問密鑰傳輸到與預期不同的服務器上。
4.捕獲任務輸入文件
（插件2.1+，Gradle 5.0+）
構建掃描捕獲任務輸入的哈希值，以便在比較構建和其他功能時識別輸入的更改。默認情況下，將捕獲每個任務輸入屬性的總體哈希值。這使得確定哪些特性改變任務（例如，源或Java編譯類路徑），但沒有哪單個文件改變。爲了識別文件更改，必須捕獲每個單獨的輸入文件的路徑和內容哈希，可以將其啓用。
4.1.何時啓用
捕獲任務輸入文件會在構建結束時增加傳輸到構建掃描服務器的數據量。如果與構建掃描服務器的網絡連接不良，則可能會增加傳輸所需的時間。此外，它可能還會增加構建掃描服務器的數據存儲要求。
該數據當前僅用於構建比較，僅在Gradle Enterprise中可用，而scans.gradle.com則不可用。如果您使用的是scans.gradle.com，則不建議您啓用任務輸入文件的捕獲。
如果您正在使用Gradle Enterprise並利用其構建緩存來加速構建，則強烈建議啓用捕獲任務輸入文件，因爲使用構建比較來識別構建之間的哪些文件已更改對診斷意外的構建緩存未命中非常有效。
4.2.如何啓用
可以通過buildScan擴展名或系統屬性以編程方式啓用任務輸入文件捕獲。
4.2.1.以編程方式
要以編程方式啓用，請使用buildScan構建掃描插件添加的擴展名。
Groovy
build.gradle
buildScan {
captureTaskInputFiles = true
}
Kotlin
build.gradle.kts
buildScan {
isCaptureTaskInputFiles = true
}
請參閱API參考。
4.2.2.通過系統屬性
要啓用而不修改構建腳本，請向構建提供scan.capture-task-input-files系統屬性。如果設置了此屬性，並且使用以外的其他任何值false（包括無值），則將啓用捕獲。如果將該屬性設置爲false，則無論任何編程設置如何，都將禁用捕獲。環境設置始終優先於程序設置。
調用構建時可以指定系統屬性：
$ ./gradlew build -Dscan.capture-task-input-files
或者，可以使用JAVA_OPTS或GRADLE_OPTS環境變量將其設置爲環境的一部分：
$ export GRADLE_OPTS=-Dscan.capture-task-input-files
或者，可以在項目的gradle.properties文件或用戶的gradle.properties文件（即~/.gradle/gradle.properties）中設置。
systemProp.scan.capture-task-input-files
有關指定系統屬性的更多信息，請參見Gradle用戶手冊的“構建環境”一章。
5.擴展構建掃描
您可以輕鬆地以標記，鏈接和值的形式在構建掃描中包括額外的自定義信息。這是用於捕獲和共享對您的構建和開發過程很重要的信息的非常強大的機制。
該信息可以是您喜歡的任何信息。您可以使用標籤標記由持續集成工具運行的所有構建CI。您可以捕獲構建發佈到的環境的名稱作爲值。您可以在諸如GitHub之類的在線工具中鏈接到構建的源修訂版。可能性是無止境。
您可以看到定製數據如何顯示在圖2中：
圖1.包含不同類型的定製數據的構建掃描
Gradle Enterprise允許列出和搜索系統中所有構建掃描。除了項目名稱，結果和其他屬性之外，您還可以通過標籤和自定義值查找和過濾構建掃描。例如，在圖3中，我們將過濾所有帶有標籤“CI”和git分支名稱爲“master”的構建掃描：
圖2. Gradle Enterprise中構建掃描的過濾列表
5.1.添加標籤
標籤通常用於指示構建的類型或類別或關鍵特徵。它們在用戶界面中突出顯示，並迅速通知用戶構建的性質。一個版本可以具有零個或多個標籤。
可以通過以下tag()方法在構建時添加它們：
Groovy
在構建的構建掃描中添加標籤
buildScan {
if (System.getenv("CI")) {
tag "CI"
} else {
tag "Local"
}
tag System.getProperty("os.name")
}
Kotlin
在構建的構建掃描中添加標籤
buildScan {
tag(if (System.getenv("CI").isNullOrEmpty()) "Local" else "CI")
tag(System.getProperty("os.name"))
}
如上面的示例所示，標籤通常在條件中作爲固定字符串應用，或者在運行時從環境中評估。但是，您無需遵循固定的規則，這些只是建議。
添加標籤的語法是：
tag(<tag>)
其中<tag>是字符串。
請注意，聲明標籤的順序不會影響構建掃描視圖。它們以字母順序顯示，所有大寫字母標籤顯示在其餘字符之前。
構建掃描插件v1.9.1 +對捕獲的標籤施加了限制：
最大標籤數：50
標籤最大長度：200個字符
5.2.添加鏈接
建築物很少孤立地居住。項目來源在哪裏？是否有該項目的在線文檔？在哪裏可以找到項目的問題跟蹤器？如果存在並且有URL，則可以將其添加到構建掃描中。
可以通過以下link()方法在構建時添加它們：
Groovy
將VCS URL添加到構建的構建掃描
buildScan {
link "VCS", "https://github.com/myorg/sample/tree/${System.getProperty("vcs.branch")}"
}
Kotlin
將VCS URL添加到構建的構建掃描
buildScan {
link("VCS", "https://github.com/myorg/sample/tree/${System.getProperty("vcs.branch")}")
}
上面的示例演示瞭如何將鏈接附加到在線VCS存儲庫，該鏈接指向作爲系統屬性提供的特定分支。
添加鏈接的語法爲：
link(<label>, <URL>)
<label>只是您選擇的字符串標識符，這對您來說意味着什麼。
您可以在圖2中看到自定義鏈接的效果，該圖顯示了標籤Source如何成爲查看構建掃描的任何人都可以跟隨的超鏈接。
構建掃描插件v1.9.1 +對捕獲的鏈接施加了限制：
最大鏈接數：20
鏈接標籤最大長度：100個字符
鏈接網址最大長度：1,000個字符
5.3.添加自定義值
沒有上下文，有些信息就沒有用。“1G”是什麼意思？您可能會猜到它代表1 GB，但是那又是什麼呢？只有在附加標籤“用於構建的最大堆大小”時，它纔有意義。例如，這同樣適用於git commit ID，可以將其解釋爲其他一些沒有合適標籤的校驗和。
自定義值是爲需要上下文的這些情況設計的。它們是標準的鍵值對，其中鍵是您選擇的字符串標籤，值也是字符串，通常是從構建環境中評估的。
可以通過以下value()方法在構建時添加它們：
Groovy
向構建的構建掃描添加自定義值
buildScan {
value "Build Number", project.buildNumber
}
Kotlin
向構建的構建掃描添加自定義值
buildScan {
value("Build Number", project.buildNumber)
}
上面的示例演示瞭如何從項目屬性讀取內部版本號（假設爲此設置了內部版本），並將其作爲自定義值附加到內部版本掃描中。
添加值的語法爲：
value(<key>, <value>)
其中<key>和<value>均爲字符串。
與標籤一樣，您可以在Gradle Enterprise中按自定義值過濾構建掃描。
構建掃描插件v1.9.1 +對捕獲的自定義值施加了限制：
最大自定義值計數：1,000
自定義值密鑰的最大長度：1,000個字符
自定義值的最大長度值：100,000個字符
5.4.在構建結束時添加數據
（插件1.2+）
如果自定義數據在構建開始時可用，那麼到目前爲止您看到的示例都可以很好地工作。但是，如果您要附加僅稍後可用的數據該怎麼辦？例如，如果clean運行了任務，則您可能希望將構建標記爲“從乾淨構建” 。但是您不知道情況是否如此，直到任務執行圖準備就緒。
構建掃描插件提供了一個buildFinished()可以在這些情況下使用的鉤子。它推遲附加自定義數據，直到構建完成運行爲止。例如，假設您想報告輸出build目錄佔用了多少磁盤空間。構建直到完成才知道這一點，因此解決方案是計算磁盤空間並將其附加到buildFinished()掛鉤中的自定義值：
Groovy
在構建結束時添加自定義磁盤使用率值
buildScan {
buildFinished {
value "Disk usage (output dir)", buildDir.directorySize().toString()
}
}
Kotlin
在構建結束時添加自定義磁盤使用率值
buildScan {
buildFinished {
value("Disk usage (output dir)", buildDir.walkTopDown().map { it.length() }.sum().toString())
}
}
該buildFinished()操作可以訪問構建的其餘部分（包括Project實例），因此它可以提取各種信息。它還有權訪問一個BuildResult實例，您可以使用該實例確定構建是否失敗，如下所示：
Groovy
從中檢查構建狀態 buildFinished()
import com.gradle.scan.plugin.BuildResult
...
buildScan {
buildFinished { BuildResult result ->
if (result.failure) {
value "Failed with", result.failure.message
}
}
}
Kotlin
從中檢查構建狀態 buildFinished()
buildScan {
buildFinished {
if (this.failure != null) {
value("Failed with", this.failure.message)
}
}
}
Gradle構建工具的
BuildListener界面也包含一個buildFinished()鉤子。但是，您不能使用它來附加自定義數據，因爲它觸發得太晚了。您可以使用鉤子之類project.afterEvaluate()的buildStarted()方法，BuildListener因爲它們可以儘早執行。
5.5.添加昂貴的數據
（插件1.15+）
您可能希望添加到構建掃描中的某些數據捕獲起來可能很昂貴。例如，捕獲Git提交ID可能需要將git命令作爲外部進程執行，這很昂貴。爲此，可以在不減慢構建速度的情況下使用以下buildScan.background()方法：
Groovy
使用 background()捕捉到的昂貴的定製值
buildScan {
background {
def commitId = "git rev-parse --verify HEAD".execute().text.trim()
value "Git Commit ID", commitId
}
}
Kotlin
使用 background()捕捉到的昂貴的定製值
import java.io.ByteArrayOutputStream
...
buildScan {
background {
val os = ByteArrayOutputStream()
exec {
commandLine("git", "rev-parse", "--verify", "HEAD")
standardOutput = os
}
value("Git Commit ID", os.toString())
}
}
該方法具有將在單獨的線程上執行的功能，該功能使Gradle可以繼續執行而不必等待昂貴的工作完成。
在完成構建併發布構建掃描之前，將完成所有後臺工作。
後臺操作引發的任何錯誤都將被記錄並捕獲到構建掃描中。
有關更多信息，請參見 buildScan.background() API reference。
5.6.通過系統屬性提供自定義數據
（插件1.3+）
到目前爲止的示例已經說明了您的構建文件或初始化腳本如何通過環境變量和系統屬性從環境中提取信息。構建掃描插件還允許您通過使用特殊命名的系統屬性來注入任何形式的自定義數據。這可以幫助您使構建文件中沒有太多與環境無關的信息，這些信息可能與大多數構建用戶都不相關。
這些系統屬性採用以下形式，具體取決於您要注入鏈接，標記還是自定義值：
-Dscan.tag.<tag>
-Dscan.link.<label>=<URL>
-Dscan.value.<key>=<value>
以下是一些具體示例，這些示例假定已將構建配置爲自動發佈構建掃描：
$ ./gradlew build -Dscan.tag.CI
$ ./gradlew build -Dscan.link.VCS=https://github.com/myorg/my-super-project/tree/my-new-feature
$ ./gradlew build "-Dscan.value.CI Build Type=QA_Build"
該功能對於持續集成構建特別有用，因爲您通常可以輕鬆配置CI工具以指定構建的系統屬性。CI工具通常能夠將系統屬性注入到內部版本中，並使用來自CI系統的信息（例如內部版本號）進行插值。
$ ./gradlew build "-Dscan.value.buildNumber=$CI_BUILD_NUMBER"
6.捕獲構建掃描ID或地址
（插件1.9+）
構建掃描的地址包含在構建末尾的輸出中。但是，您可能希望以其他方式記錄構建掃描的ID或URL。構建掃描插件允許您註冊將接收此信息的回調。成功發佈構建掃描後，將調用該回調。
以下示例構建腳本片段顯示了此功能，用於維護創建的構建掃描的日誌。
Gradle Enterprise提供了搜索特定用戶和/或特定主機創建的構建掃描的能力（以及其他搜索條件）。
Gradle Enterprise提供了搜索特定用戶和/或特定主機創建的構建掃描的能力（以及其他搜索條件）。Groovy
創建已發佈的構建掃描日誌
import com.gradle.scan.plugin.PublishedBuildScan
...
buildScan {
buildScanPublished { PublishedBuildScan scan ->
file("scan-journal.log") << "${new Date()} - ${scan.buildScanId} - ${scan.buildScanUri}\n"
}
}
Kotlin
創建已發佈的構建掃描日誌
import java.util.Date
...
buildScan {
buildScanPublished {
file("scan-journal.log").appendText("${Date()} - ${this.buildScanId} - ${this.buildScanUri}\n")
}
}
請參閱buildScan.buildScanPublished()方法以獲取API詳細信息。
7.混淆識別數據
（插件2.4.2+）
構建掃描捕獲某些標識信息，例如操作系統用戶名，主機名和網絡地址。通過將混淆功能註冊爲構建掃描插件配置的一部分，您可以選擇對這些數據進行模糊處理，以使其在構建掃描中無法被解密。
以下示例顯示爲不同的標識數據註冊混淆功能。
Groovy/Kotlin
混淆用戶名
buildScan {
obfuscation {
username { name -> name.reverse() }
}
}
混淆主機名
buildScan {
obfuscation {
hostname { host -> host.collect { character -> Character.getNumericValue(character as char) }.join("-") }
}
}
混淆IP地址
buildScan {
obfuscation {
ipAddresses { addresses -> addresses.collect { address -> "0.0.0.0"} }
}
}
8.整合許多項目
儘管通常將此插件直接應用於項目，但也可以使用Gradle的init腳本功能來將其應用於輕鬆地將其應用於許多項目。這通常用於啓用環境中所有構建的集成（即CI構建或開發人員的機器）。
初始化腳本可以與Gradle一起使用，方法是在構建時使用以下-I選項指定腳本的路徑：
$ ./gradlew build -I path/to/init.gradle
或者可以將它們放置在~/.gradle/init.d目錄中以自動應用到非常構建。
8.1.Gradle Enterprise
以下初始化腳本示例使任何Gradle 5.0或更高版本的構建都可以與Gradle Enterprise服務器集成：
Groovy
gradle-enterprise-init.gradle
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion
initscript {
def pluginVersion = "3.1.1"
repositories {
gradlePluginPortal()
}
dependencies {
classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
}
}
def isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
def gradleVersion = GradleVersion.current().baseVersion
def atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
def atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")
if (atLeastGradle6) {
settingsEvaluated {
if (!it.pluginManager.hasPlugin("com.gradle.enterprise")) {
it.pluginManager.apply(GradleEnterprisePlugin)
}
configureExtension(it.extensions["gradleEnterprise"].buildScan)
}
} else if (atLeastGradle5) {
rootProject {
pluginManager.apply(BuildScanPlugin)
configureExtension(extensions["buildScan"])
}
}
}
void configureExtension(extension) {
extension.with {
publishAlways()
server = "https://gradle-enterprise.company.com"
// other configuration
}
}
Kotlin
gradle-enterprise-init.gradle.kts
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion
initscript {
val pluginVersion = "3.1.1"
repositories {
gradlePluginPortal()
}
dependencies {
classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
}
}
val isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
val gradleVersion = GradleVersion.current().baseVersion
val atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
val atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")
if (atLeastGradle6) {
settingsEvaluated {
if (!pluginManager.hasPlugin("com.gradle.enterprise")) {
pluginManager.apply(GradleEnterprisePlugin::class)
}
extensions["gradleEnterprise"].withGroovyBuilder {
configureExtension(getProperty("buildScan"))
}
}
} else if (atLeastGradle5) {
rootProject {
pluginManager.apply(BuildScanPlugin::class)
configureExtension(extensions["buildScan"])
}
}
}
fun configureExtension(extension: Any) {
extension.withGroovyBuilder {
"publishAlways"()
setProperty("server", "https://gradle-enteprise.company.com")
// other configuration
}
}
8.2.scans.gradle.com
以下初始化腳本示例使任何Gradle 5.0或更高版本的構建都可以與scans.gradle.com集成：
Groovy
scans-init.gradle
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion
initscript {
def pluginVersion = "3.1.1"
repositories {
gradlePluginPortal()
}
dependencies {
classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
}
}
def isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
def gradleVersion = GradleVersion.current().baseVersion
def atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
def atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")
if (atLeastGradle6) {
settingsEvaluated {
if (!it.pluginManager.hasPlugin("com.gradle.enterprise")) {
it.pluginManager.apply(GradleEnterprisePlugin)
}
configureExtension(it.extensions["gradleEnterprise"].buildScan)
}
} else if (atLeastGradle5) {
rootProject {
pluginManager.apply(BuildScanPlugin)
configureExtension(extensions["buildScan"])
}
}
}
void configureExtension(extension) {
extension.with {
termsOfServiceUrl = "https://gradle.com/terms-of-service"
termsOfServiceAgree = "yes"
// other configuration
}
}
Kotlin
scans-init.gradle.kts
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion
initscript {
val pluginVersion = "3.1.1"
repositories {
gradlePluginPortal()
}
dependencies {
classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
}
}
val isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
val gradleVersion = GradleVersion.current().baseVersion
val atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
val atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")
if (atLeastGradle6) {
settingsEvaluated {
if (!pluginManager.hasPlugin("com.gradle.enterprise")) {
pluginManager.apply(GradleEnterprisePlugin::class)
}
extensions["gradleEnterprise"].withGroovyBuilder {
configureExtension(getProperty("buildScan"))
}
}
} else if (atLeastGradle5) {
rootProject {
pluginManager.apply(BuildScanPlugin::class)
configureExtension(extensions["buildScan"])
}
}
}
fun configureExtension(extension: Any) {
extension.withGroovyBuilder {
setProperty("termsOfServiceUrl", "https://gradle.com/terms-of-service")
setProperty("termsOfServiceAgree", "yes")
// other configuration
}
}
9.升級到Gradle 6
如果您以前在Gradle 5中使用了構建掃描插件2.x，則升級到3.x插件不僅需要更新版本號。插件的ID已更改，現在必須將其應用於構建的設置文件中。
要升級，請首先找到應用2.x插件的位置並刪除它。這可能在根目錄build.gradle或build.gradle.kts文件中，並且看起來類似於以下內容：
Groovy
build.gradle
plugins {
id "com.gradle.build-scan" version "2.4.2"
}
Kotlin
build.gradle.kts
plugins {
id("com.gradle.build-scan").version("2.4.2")
}
然後，將以下內容添加到構建的settings.gradle或settings.gradle.kts文件中：
Groovy
settings.gradle
plugins {
id "com.gradle.enterprise" version "3.1.1"
}
Kotlin
settings.gradle.kts
plugins {
id("com.gradle.enterprise").version("3.1.1")
}
任何buildScan {}配置都可以保留在原處，或移動到gradleEnterprise {}塊內的設置文件中。有關更多信息，請參見上面的Gradle 6.x部分。
Groovy
settings.gradle
gradleEnterprise {
buildScan {
server = "https://gradle-enterprise.company.com"
}
}
Kotlin
settings.gradle.kts
gradleEnterprise {
buildScan {
server = "https://gradle-enterprise.company.com"
}
}
10.Gradle 4.x及更早版本
10.1.Gradle 2.1 - 4.10.2
低於5.0的Gradle版本與最新的插件和功能不兼容。插件1.16是此類構建的最佳可用版本。插件必須以ID應用於構建的根項目com.gradle.build-scan。
Groovy
build.gradle
plugins {
id "com.gradle.build-scan" version "1.16"
}
Kotlin
build.gradle.kts
plugins {
id("com.gradle.build-scan") version "1.16"
}
10.1.Gradle 2.0
Gradle 2.0不支持plugins {}Gradle 2.1中引入的語法。因此，插件必須以不同的方式應用。
Groovy
build.gradle
buildscript {
repositories {
maven { url "https://plugins.gradle.org/m2/" }
}
dependencies {
classpath "com.gradle:build-scan-plugin:1.16"
}
}
apply plugin: "com.gradle.build-scan"
Kotlin
build.gradle.kts
buildscript {
repositories {
maven(url = "https://plugins.gradle.org/m2/")
}
dependencies {
classpath("com.gradle:build-scan-plugin:1.16")
}
}
apply(plugin = "com.gradle.build-scan")
11.故障排除
11.1.主機名解析速度慢
如果在構建期間看到警告，提示解析本地主機名的速度很慢，則可以通過將主機名映射添加到/etc/hosts文件中來解決此問題。
將這些行添加到/etc/hosts文件中，在下面的代碼段中將您的計算機名稱替換爲“mbpro”：
/etc/hosts
127.0.0.1 localhost mbpro.local
::1 localhost mbpro.local
附錄A：API參考
請參閱Javadoc。
附錄B：捕獲的信息
構建掃描插件會在構建運行時捕獲信息，並在構建完成後將其傳輸到服務器。
捕獲的大多數信息都可以視爲構建數據。這包括構建中項目的名稱，任務，插件，依賴項，名稱和測試結果以及其他性質的東西。還捕獲了一些更一般的環境信息。這包括您的Java版本，操作系統，硬件，國家/地區，時區和其他此類性質。
值得注意的是，沒有捕獲正在構建的實際源代碼和輸出工件。但是，編譯器發出的錯誤消息或測試中的錯誤可能會揭示源代碼的某些方面。
清單
下面的列表詳細說明了由構建掃描插件捕獲並在構建掃描中傳輸的重要信息。
-
環境
-
建立
-
Gradle命令行和調用選項（例如，請求的任務，開關）
-
構建控制檯輸出
-
構建失敗異常消息和堆棧跟蹤
-
建立棄用消息
-
項目名稱和結構
-
Gradle Daemon操作數據（例如開始時間，構建計數）
-
構建緩存配置
-
Gradle生命週期回調
-
訪問
可以訪問服務器的所有用戶都可以查看發佈到Gradle Enterprise安裝的內部版本掃描。Gradle Enterprise提供了一個搜索界面，用於發現和查找單獨的構建掃描。
任何人都可以查看發佈到scans.gradle.com的構建掃描，並在發佈構建掃描時指定了鏈接。指向各個構建掃描的鏈接不可發現，無法猜測，但可以共享。
附錄C：插件發行歷史
3.1.1-2019年12月13日，
當構建掃描發佈需要身份驗證時，改進了幫助消息
抑制了由於使用工件轉換而導致的構建掃描中的過多日誌記錄，
如果在macOS上本地主機名解析速度較慢，則可以緩解
3.1-2019年11月25日
支持訪問密鑰配置將
響應的MIME類型從'text / *'更改爲'application / *'
在特殊情況下的固定事件排序
3.0-2019年10月16日
更名爲Gradle Enterprise插件
與Gradle 6的兼容性
2.4.2-2019年9月10日，
增加了對用戶名，主機名和IP地址混淆的支持
2.4.1-2019年8月20日，
更可靠地捕獲日誌記錄輸出
以依賴項解析方式處理重疊的ID
更穩定的構建結束處理
2.4-2019年8月8日
添加了對捕獲所有依賴項選擇原因的
支持添加了對捕獲依賴項變體詳細信息的
支持添加了對捕獲豐富的依賴項版本約束信息的
支持添加了對捕獲依賴項平臺和約束詳細信息的支持
2.3-2019年5月3日
添加了對插件複合構建的
支持添加了對連續構建的
支持添加了對捕獲Java編譯期間使用的註釋處理器的詳細信息的支持
2.2.1- 2019年3月1日，更可靠地捕獲buildSrc的任務輸入文件
2019年2月2.2日至27日，
捕獲收集回調的執行
更加緊湊地捕獲了棄用跟蹤
，任務輸入捕獲中的總體性能改進
2.1-2018年12月7日
此版本與Java 8和更高版本的
Capture任務輸入文件兼容
2.0.2- 2018年11月6日，
此版本與Gradle 5.0兼容，並
刪除了已棄用的-Dscan和-Dscan = false系統屬性，分別使用--scan和--no-scan
避免經常連接到HTTPS服務器時發生內存泄漏更改構建類路徑
2.0.1-2018年10月29日，
此版本發行是爲了與Gradle 5.0-rc-1
兼容，但與後續的Gradle 5.0版本不兼容。請改用2.0.2或更高版本。
2.0-2018年10月17日，
此版本發佈是爲了與Gradle 5.0-milestone-1
兼容，但與後續的Gradle 5.0版本不兼容。請改用2.0.2或更高版本。
1.16-2018年8月21日，
捕獲已解決的模塊組件的存儲庫和源存儲庫
捕獲單個生命週期偵聽器和代碼單元應用程序的屬性
捕獲Gradle構建腳本編譯詳細信息
捕獲已棄用的使用通知
捕獲包含的構建源
1.15.2-2018年8月10日，
修復Kotlin腳本構建緩存
1.15.1- 2018年7月5日，使用buildScan.background（）修復了潛在的類加載器泄漏
1.15- 2018年7月3日
支持在後臺捕獲昂貴的自定義值/標籤/鏈接
任務buildScanPublishPrevious懶惰地創建
修復了將包含的構建用作插件和主構建時的錯誤
1.14-2018年6月12日
進一步的性能改進
消除不必要的隱式連續構建掃描抑制
捕獲有關生命週期掛鉤執行的信息
1.13.4-2018年5月18日
，尤其是在配置期間，改進了構建掃描插件的性能
1.13.3-2018年5月14日
，使用Gradle 4.7中的新連續構建功能修復了不兼容性
1.13.2-2018年5月8日，
當存在--quiet或-q參數存在時不顯示構建掃描發佈信息，在發佈構建掃描時
重試可能的臨時網絡錯誤
1.13.1-2018年4月10日
提高插件數據捕獲的性能。
1.13-2018年3月28日，
從構建開始就捕獲控制檯日誌。
1.12.1-2018年2月13日
，服務條款被拒絕時修復消息。
1.12-2018年2月12日
捕獲合成版本的構建掃描。
捕獲原始任務執行時間。
1.11-2017年12月5日
，從構建開始就捕獲測試執行，依賴關係解析和項目結構數據。
提高插件數據捕獲的性能。
增強Gradle版本兼容性檢查。
1.10.3-2017年11月23日，
修復了與Gradle 3.0.0的Android插件不兼容的問題。
1.10.2-2017年11月7日，
修復了與Gradle 4.4的開發版本不兼容的問題。
1.10.1-2017年10月27日，
修復了與Gradle 4.4的開發版本不兼容的問題。
1.10-2017年10月17日，
檢測何時由單一用途守護程序運行構建。
捕獲執行構建的JVM的默認字符集。
捕獲每個項目的構建路徑。
1.9.1-2017年10月10日
，如果需要，提示用戶接受許可協議。
捕獲控制檯輸出和網絡活動，直到接近構建結束。
限制捕獲的定製標記，定製鏈接和定製值的數量和長度。
1.9-2017年8月15日，
捕獲任務圖計算。
捕獲更多細粒度的項目配置。
捕獲構建緩存交互，包括工件打包和解包。
2017年6月1.8日-15日
捕獲已解決的請求任務。
啓用構建緩存後，捕獲構建緩存配置。
啓用構建緩存後，捕獲每個任務的任務輸入。
捕獲具有最新和從緩存結果的任務的原始構建調用ID。
記錄爲什麼任務不是最新的原因。
捕獲GC和堆內存峯值統計信息。
捕獲更多的網絡下載活動。
在通過buildScan.buildScanPublished（）成功進行構建掃描發佈後獲得通知。
在安靜級別構建掃描插件日誌。
1.7.4-2017年5月29日，
修復了與Gradle 4.0的開發版本不兼容的問題。
1.7.3-2017年5月19日，
修復了與Gradle 4.0的開發版本不兼容的問題。
1.7.2-2017年5月17日，
修復了與Gradle 4.0的開發版本不兼容的問題。
1.7.1-2017年5月3日，
修復了與Gradle 4.0的開發版本不兼容的問題。
1.7-2017年4月24日，
當指定不帶模式或主機的buildScan“服務器” URL時，修復NPE。
重疊輸出被捕獲爲任務的不可緩存原因。
2017年2月1.6日至10月10日，
捕獲任務輸出是否可緩存以及它們是否不可緩存的原因。
捕獲網絡下載活動。
2017年1月1.5日至1月11日，
捕獲是否由於沒有源而跳過了任務。
捕獲任務是否是生命週期任務（即無操作）。
添加“ mailto：”鏈接作爲自定義生成掃描鏈接。
1.4-2016年12月21日
，執行許多測試時的性能提高。
2016年11月1.3日至15日
通過常規系統屬性捕獲標籤，鏈接和/或值。
發佈較大的依賴圖時減小有效負載大小。
2016年10月1.2日至12月12日
，通過buildScan.buildFinished（）捕獲標記，鏈接和/或值。
1.1.1-2016年9月20日，已
解決通過Android Studio爲某些項目創建構建掃描的問題。
2016年9月1.1日至17日
捕獲用戶定義的標籤，鏈接和任意值。
爲每個構建或每個失敗的構建創建一個構建掃描。
爲上一個之前的版本創建一個版本掃描。
使用--offline構建時，將隱式禁用發佈構建掃描。
如果顯式配置，則通過不受信任的HTTPS連接發佈構建掃描。
通過IDE執行構建時，用於創建構建掃描的多個修復程序。
1.0-2016年6月23日
初始版本。
附錄D：與Gradle Build Tool和Gradle Enterprise的插件兼容性
可以在此處找到Gradle，Gradle Enterprise和構建掃描插件的版本之間的兼容性。