connectedhomeip 倉(cāng)庫(kù) Android 第三方依賴(lài)管理指南chipDeps、set_up_android_deps.py 與 GN 構(gòu)建目標(biāo)生成【免費(fèi)下載鏈接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip導(dǎo)讀本文面向在 Matterconnectedhomeip倉(cāng)庫(kù)中開(kāi)發(fā) Android 應(yīng)用的工程師系統(tǒng)講解該倉(cāng)庫(kù)如何管理 Android 第三方依賴(lài)從在 Gradle 中聲明chipDeps依賴(lài)、通過(guò)set_up_android_deps.py一鍵下載 JAR 并生成 GN 構(gòu)建目標(biāo)到最終在應(yīng)用BUILD.gn中引用依賴(lài)的完整鏈路。讀完本文你將掌握為倉(cāng)庫(kù)新增一個(gè) Android 依賴(lài)的標(biāo)準(zhǔn)操作流程并理解其背后 Gradle 解析 Groovy 任務(wù)生成 GN 編譯消費(fèi) 的雙構(gòu)建系統(tǒng)銜接原理。一、目錄職責(zé)一個(gè)目錄、兩套構(gòu)建體系的橋梁third_party/android_deps/是 connectedhomeip 中專(zhuān)門(mén)用于管理 Android 第三方依賴(lài)的目錄。其設(shè)計(jì)目標(biāo)是解決一個(gè)核心矛盾Matter 的整體構(gòu)建基于 GN.gn/.gni文件而 Android 依賴(lài)的解析與下載天然屬于 Gradle 生態(tài)。該目錄通過(guò)一套定制腳本把兩者銜接起來(lái)。目錄內(nèi)各文件職責(zé)如下文件職責(zé)third_party/android_deps/README.md使用說(shuō)明本文所依據(jù)的官方文檔third_party/android_deps/android_deps.gradle定義chipDeps配置及依賴(lài)聲明被build.gradle引入實(shí)現(xiàn)配置共享third_party/android_deps/build.gradle定義setUpAndroidDepsGnBuildGenerator類(lèi)型與copyArtifacts兩個(gè) Gradle 任務(wù)third_party/android_deps/set_up_android_deps.py一鍵入口腳本調(diào)用 Gradle 任務(wù)生成BUILD.gn隨后用gn format統(tǒng)一格式third_party/android_deps/buildSrc/src/main/groovy/GnBuildGenerator.groovy核心生成器解析chipDeps依賴(lài)樹(shù)輸出java_prebuilt目標(biāo)third_party/android_deps/BUILD.gn自動(dòng)生成的 GN 構(gòu)建目標(biāo)文件需提交入庫(kù)third_party/android_deps/artifacts/下載的 JAR 二進(jìn)制目錄禁止入庫(kù)third_party/android_deps/gradlew/gradlew.bat/gradle/wrapper/Gradle Wrapper固定構(gòu)建所用 Gradle 版本當(dāng)前為 Gradle 8.7見(jiàn)gradle/wrapper/gradle-wrapper.properties二、添加新依賴(lài)的標(biāo)準(zhǔn)流程根據(jù) README.md 的官方說(shuō)明為倉(cāng)庫(kù)新增一個(gè) Android 依賴(lài)只需三步。2.1 第一步在chipDeps配置中聲明依賴(lài)編輯 third_party/android_deps/android_deps.gradle在dependencies塊中為chipDeps配置添加依賴(lài)。該文件當(dāng)前內(nèi)容如下// This file is kept separate from build.gradle, so that the chipDeps configuration it defines can be shared. apply plugin: base repositories { google() mavenCentral() } configurations { chipDeps } dependencies { chipDeps androidx.annotation:annotation:1.1.0 }要點(diǎn)說(shuō)明倉(cāng)庫(kù)源依賴(lài)從google()與mavenCentral()兩個(gè) Maven 倉(cāng)庫(kù)解析覆蓋了 AndroidX 官方庫(kù)與 Maven Central 上的絕大多數(shù)開(kāi)源 JARchipDeps命名該配置是一個(gè)自定義 Gradle configuration僅用于收集需要轉(zhuǎn)譯為 GN 目標(biāo)的依賴(lài)與應(yīng)用自身的implementation/api配置完全解耦當(dāng)前示例倉(cāng)庫(kù)默認(rèn)依賴(lài)androidx.annotation:annotation:1.1.0即 AndroidX 注解庫(kù)為 Android 側(cè)代碼提供NonNull、Nullable等注解支持文件拆分原因注釋中明確指出該文件與build.gradle分離是為了讓chipDeps配置可以被共享被build.gradle通過(guò)apply from: android_deps.gradle引入。新增依賴(lài)時(shí)按group:name:version格式追加即可例如chipDeps com.google.code.gson:gson:2.10.1。2.2 第二步運(yùn)行一鍵腳本在倉(cāng)庫(kù)根目錄執(zhí)行./set_up_android_deps.py該腳本完成兩件事見(jiàn) third_party/android_deps/set_up_android_deps.py調(diào)用 Gradle Wrapper 執(zhí)行setUpAndroidDeps任務(wù)對(duì)生成的BUILD.gn執(zhí)行g(shù)n format規(guī)范化格式。腳本實(shí)現(xiàn)細(xì)節(jié)源碼級(jí)說(shuō)明def main(): chip_root os.getenv(PW_PROJECT_ROOT) android_deps_dir os.path.join(chip_root, third_party/android_deps) gradlew gradlew if sys.platform ! win32 else gradlew.bat gradle_executable os.path.join(android_deps_dir, gradlew) subprocess.check_call( [gradle_executable, -p, android_deps_dir, setUpAndroidDeps]) subprocess.check_call( [gn, format, os.path.join(android_deps_dir, BUILD.gn)])值得注意的運(yùn)行前提腳本通過(guò)環(huán)境變量PW_PROJECT_ROOT定位倉(cāng)庫(kù)根目錄——這是 Pigweed 環(huán)境變量體系的一部分意味著通常需要在已激活的 Matter 構(gòu)建環(huán)境中運(yùn)行跨平臺(tái)友好Windows 上自動(dòng)切換為gradlew.bat其余平臺(tái)使用gradlew腳本依賴(lài)系統(tǒng)中存在gn命令位于 PATH用于最后一步格式化。2.3 第三步在應(yīng)用代碼中引用生成的目標(biāo)依賴(lài)下載完成后JAR 落入artifacts/目錄GN 目標(biāo)寫(xiě)入BUILD.gn。應(yīng)用代碼通過(guò)以下形式引用deps [ ${chip_root}/third_party/android_deps:my_dep, ]目標(biāo)命名規(guī)則GN 目標(biāo)名由 Gradle 依賴(lài)名自動(dòng)推導(dǎo)。官方示例中androidx.annotation:annotation:1.1.0生成的構(gòu)建目標(biāo)名為annotation。推導(dǎo)依據(jù)是 Gradle 依賴(lài)坐標(biāo)的 artifact 部分即三段坐標(biāo)group:name:version中的name。當(dāng)前倉(cāng)庫(kù)自動(dòng)生成的 BUILD.gn 內(nèi)容如下# This BUILD file is auto-generated, modify the GnBuildGenerator task instead of editing this file manually. import(//build_overrides/chip.gni) import(${chip_root}/build/chip/java/rules.gni) java_prebuilt(annotation) { jar_path artifacts/annotation-1.1.0.jar }文件中java_prebuilt來(lái)自${chip_root}/build/chip/java/rules.gni中定義的 Chip Java 構(gòu)建規(guī)則其jar_path指向相對(duì)本目錄的下載產(chǎn)物。2.4 實(shí)際消費(fèi)示例倉(cāng)庫(kù)中的真實(shí)引用annotation目標(biāo)已在倉(cāng)庫(kù)中被實(shí)際消費(fèi)可在以下兩個(gè)文件中找到引用src/app/server/java/BUILD.gn#L58${chip_root}/third_party/android_deps:annotationsrc/platform/android/BUILD.gn#L127${chip_root}/third_party/android_deps:annotation這表明annotation目標(biāo)服務(wù)于 Matter 的 Android 服務(wù)器app server與平臺(tái)層代碼是驗(yàn)證聲明 → 下載 → 生成 → 消費(fèi)閉環(huán)的真實(shí)用例新增依賴(lài)時(shí)可參照這兩個(gè)位置補(bǔ)全deps。三、提交與忽略策略哪些該入庫(kù)哪些不該入庫(kù)README 明確給出兩條版本管理紀(jì)律BUILD.gn必須提交入庫(kù)因?yàn)樗菢?gòu)建入口開(kāi)發(fā)者需要追蹤依賴(lài)最終指向哪里即每個(gè)依賴(lài)對(duì)應(yīng)哪個(gè) JAR 文件提交后所有開(kāi)發(fā)者無(wú)需重新運(yùn)行生成腳本即可構(gòu)建artifacts/禁止提交該目錄存放的是 JAR 二進(jìn)制文件體積大且可由腳本隨時(shí)重新下載屬于典型的構(gòu)建產(chǎn)物。這一策略與build.gradle中的clean任務(wù)相互呼應(yīng)clean { delete artifacts }即執(zhí)行 Gradleclean時(shí)會(huì)清空artifacts/進(jìn)一步確認(rèn)其可再生產(chǎn)物的定位。四、底層原理GnBuildGenerator 如何把 Gradle 依賴(lài)樹(shù)變成 GN 目標(biāo)setUpAndroidDeps任務(wù)的類(lèi)型是 GnBuildGenerator.groovy位于 Gradle 的buildSrc中隨倉(cāng)庫(kù)編譯這是整個(gè)機(jī)制的核心。其工作流如下。4.1 Gradle 任務(wù)編排build.gradlethird_party/android_deps/build.gradle 中定義了兩個(gè)任務(wù)及其依賴(lài)關(guān)系apply plugin: base apply from: android_deps.gradle task setUpAndroidDeps(type: GnBuildGenerator) {} task copyArtifacts(type: Copy) { // Defined in android_deps.gradle from configurations.chipDeps into artifacts } clean { delete artifacts } setUpAndroidDeps.dependsOn copyArtifactscopyArtifacts把chipDeps配置解析出的所有 JAR 拷貝到artifacts/目錄setUpAndroidDeps執(zhí)行GnBuildGenerator且依賴(lài)copyArtifacts保證先有 JAR 再生成BUILD.gn。4.2 依賴(lài)樹(shù)遍歷與目標(biāo)生成生成器通過(guò) Gradle 的解析 API 獲得依賴(lài)圖firstLevelModuleDependencies及其children隨后對(duì)每個(gè)模塊輸出一個(gè)java_prebuilt目標(biāo)chipDepsConfiguration.resolvedConfiguration.firstLevelModuleDependencies.each { allDeps it it.children.each { allDeps it } } allDeps.each { def artifact it.moduleArtifacts[0] // ... 校驗(yàn)邏輯 ... stringBuilder.append(java_prebuilt(\$it.module.id.name\) {\n) stringBuilder.append( jar_path \$COPIED_ARTIFACTS_DIR/${artifact.file.name}\\n) // ... }值得強(qiáng)調(diào)的工程細(xì)節(jié)傳遞依賴(lài)自動(dòng)展開(kāi)不僅處理一級(jí)依賴(lài)還遞歸收集所有子依賴(lài)children因此聲明的庫(kù)若帶有傳遞依賴(lài)也會(huì)一并生成 GN 目標(biāo)傳遞依賴(lài)的deps關(guān)聯(lián)子依賴(lài)會(huì)以deps [:子依賴(lài)名]的形式掛到父目標(biāo)上保持依賴(lài)圖在 GN 側(cè)同樣完整嚴(yán)格的產(chǎn)物校驗(yàn)若某個(gè)模塊產(chǎn)生多個(gè)頂層產(chǎn)物moduleArtifacts.size() 1或產(chǎn)物擴(kuò)展名不是jar生成器會(huì)拋出IllegalStateException終止任務(wù)。這限制了當(dāng)前方案僅支持單 JAR 形式的庫(kù)——AAR 或其他打包形式不在支持范圍內(nèi)頭部自動(dòng)生成生成的BUILD.gn自動(dòng)拼接copyright_header.txt的版權(quán)頭與GENERATED_WARNING警告行警告明確要求修改生成邏輯而非手工編輯BUILD.gn。4.3 目標(biāo)命名的一致性GN 目標(biāo)名取自it.module.id.nameGradle 模塊坐標(biāo)的 name 部分與 README 所述 androidx.annotation:annotation:1.1.0 變?yōu)?annotation 完全一致也與生成的BUILD.gn中java_prebuilt(annotation)相互印證。五、常見(jiàn)問(wèn)題與操作注意事項(xiàng)基于源碼可以總結(jié)出以下實(shí)操注意點(diǎn)環(huán)境變量缺失導(dǎo)致腳本失敗set_up_android_deps.py依賴(lài)PW_PROJECT_ROOT定位倉(cāng)庫(kù)根目錄建議在 Matter 開(kāi)發(fā)環(huán)境如執(zhí)行過(guò)scripts/activate.sh的 shell中運(yùn)行不支持 AAR 依賴(lài)生成器的校驗(yàn)邏輯只接受單一jar產(chǎn)物。AndroidX 中的 UI 組件庫(kù)如androidx.appcompat、androidx.recyclerview通常以 AAR 發(fā)布不適用于此流程需要引入 AAR 時(shí)應(yīng)考慮其他方案如build/chip/java/rules.gni中的既有規(guī)則或在倉(cāng)庫(kù)中另行處理生成結(jié)果需復(fù)審后提交運(yùn)行腳本后應(yīng)git diff檢查BUILD.gn變化確認(rèn)目標(biāo)名、jar_path與預(yù)期一致再提交入庫(kù)artifacts/不要手動(dòng)提交若誤提交可通過(guò)clean任務(wù)清理后再行處理注意倉(cāng)庫(kù)為只讀研究環(huán)境此處僅描述常規(guī)開(kāi)發(fā)流程Gradle 版本固定項(xiàng)目通過(guò) gradle/wrapper/gradle-wrapper.properties 鎖定 Gradle 8.7首次運(yùn)行 Wrapper 會(huì)自動(dòng)下載對(duì)應(yīng)發(fā)行版。六、小結(jié)connectedhomeip 通過(guò)third_party/android_deps/實(shí)現(xiàn)了用 Gradle 聲明與解析、用 GN 編譯與鏈接的混合依賴(lài)管理模式開(kāi)發(fā)者只需在android_deps.gradle中追加一行chipDeps聲明運(yùn)行./set_up_android_deps.py即可自動(dòng)完成 JAR 下載與BUILD.gn目標(biāo)生成隨后在任意應(yīng)用目標(biāo)的deps中以${chip_root}/third_party/android_deps:name形式引用。這套流程的核心價(jià)值在于把第三方 Android 依賴(lài)的版本管理收斂到一處 Gradle 文件同時(shí)把構(gòu)建產(chǎn)物JAR與構(gòu)建描述GN 目標(biāo)嚴(yán)格區(qū)分提交策略兼顧了依賴(lài)可追蹤性與倉(cāng)庫(kù)清潔度是理解 Matter Android 構(gòu)建鏈路的必讀入口?！久赓M(fèi)下載鏈接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考