ProfileInstaller

  
在 ART 讀取時間編譯追蹤記錄之前,讓程式庫預先填入。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2024 年 10 月 2 日 1.4.1 - - -

宣告依附元件

如果要為 ProfileInstaller 新增依附元件,您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區

在應用程式或模組的 build.gradle 檔案中,新增所需構件的依附元件:

Groovy

dependencies {
    implementation "androidx.profileinstaller:profileinstaller:1.4.1"
}

Kotlin

dependencies {
    implementation("androidx.profileinstaller:profileinstaller:1.4.1")
}

如要進一步瞭解依附元件,請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題,或是有改進這個程式庫的建議,請告訴我們。回報新問題前,請先查看這個程式庫的現有問題。只要按一下星號按鈕,即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件

1.4 版

1.4.1 版本

2024 年 10 月 2 日

發布 androidx.profileinstaller:profileinstaller:1.4.1。1.4.1 版包含這些修訂項目

修正錯誤

  • 修正透過依序傳送多個程序信號,對多程序基準設定檔記錄的支援。修正此問題時,您必須在 Macrobenchmark/基準設定檔模組中更新為 androidx.benchmark:benchmark-macro:1.4.0-alpha02,以及在應用程式中更新為 androidx.profileinstaller:profileinstaller:1.4.1 (I0f519b/366231469)。

1.4.0 版本

2024 年 9 月 18 日

發布 androidx.profileinstaller:profileinstaller:1.4.0。1.4.0 版包含這些修訂版本

自 1.3.0 版以來的重要異動

  • ProfileInstaller 現在支援在 API 35 以上版本擷取/安裝設定檔。平台版本更新不再需要更新 ProfileInstaller。(6f9f6fa)。
  • 修正在 Android U (API 34) 和模擬器上放置著色器時發生的異常終止問題。(I031cab/274314544)。
  • 修正 V_015S 設定檔格式中的轉碼方法標記。(aosp/2906631aosp/2847740)

1.4.0-rc01 版本

2024 年 9 月 4 日

發布 androidx.profileinstaller:profileinstaller:1.4.0-rc01,該版本與上一個 Beta 版沒有差別。1.4.0-rc01 版本包含這些修訂項目

1.4.0-beta01 版本

2024 年 8 月 21 日

發布 androidx.profileinstaller:profileinstaller:1.4.0-beta01,該版本與上一個 Alpha 版沒有差別。1.4.0-beta01 版包含這些修訂項目

1.4.0-alpha02 版

2024 年 8 月 7 日

發布 androidx.profileinstaller:profileinstaller:1.4.0-alpha02。1.4.0-alpha02 版包含這些修訂項目

新功能

  • 為設定檔安裝程式新增 API 35 支援。(6f9f6fa)。

修正錯誤

  • 移除新平台 API 存取權的手動設定,因為在使用 AGP 7.3 以上版本 (例如 R8 3.3 版) 的 R8 時,以及在使用 AGP 8.1 以上版本 (例如 D8 8.1 版) 的所有版本時,系統會透過 API 模擬功能自動執行此操作。建議未使用 AGP 的用戶端更新至 D8 8.1 以上版本。詳情請參閱這篇文章。(If6b4cb/345472586)。

1.4.0-alpha01 版

2024 年 2 月 7 日

發布 androidx.profileinstaller:profileinstaller:1.4.0-alpha011.4.0-alpha01 版包含此連結所列的修訂項目

修正錯誤

  • 新增錯誤代碼,用於檢查未嵌入設定檔的情況。(Ifb109b/313928520)。
  • 修正在 Android U (API 34) 和模擬器上放置著色器時發生的異常終止問題。(I031cab/274314544)。
  • 在設定檔安裝程式中啟用 Android U 支援功能。(Iaf177)。
  • 修正了程序啟動時,Android U 上的設定檔安裝程式失敗的問題。(Ie3899)。
  • 修正 V_015S 設定檔格式的方法點陣圖轉碼。(aosp/2906631) 和 (aosp/2847740)

1.3 版本

1.3.1 版本

2023 年 5 月 3 日

發布 androidx.profileinstaller:profileinstaller:1.3.1查看 1.3.1 版的修訂項

修正錯誤

  • 在設定檔安裝程式中啟用 Android U 支援功能 (Iaf177)
  • 修正了程序啟動時,Android U 上的設定檔安裝程式失敗的問題。(Ie3899)。

1.3.0 版本

2023 年 3 月 22 日

發布 androidx.profileinstaller:profileinstaller:1.3.01.3.0 版包含此連結所列的修訂項目。

自 1.2.0 版以來的重要異動

  • 修正了 ProfileInstallReceiver 中發生的 NullPointerException。(b/243851384)。
  • 新增了 ProfileVerifier API,用於在應用程式中檢查是否已編譯、排程或缺少基準設定檔 (I263a4b/246653809)
  • 新增殼層播送,這可讓 Macrobenchmark 將記憶體內設定檔資料全部清除至磁碟,以包含在基準設定檔產生中。必須使用 Macrobenchmark 程式庫,才能透過 BaselineProfileRule 擷取基準設定檔,並使用 CompilationMode.Partial(warmupIterations) 評估設定檔效能。
  • 新增診斷碼,用於偵測經過壓縮的基準設定檔。由於 CPU 額外負擔,Profileinstaller 無法在 Macrobenchmark 或實際環境中安裝壓縮的基準設定檔,因此建構應用程式時,請避免更新至 Studio/AGP Electric Eel 或 bundletool 版本 1.13.1(I86413b/261998144)
  • 新增 Macrobenchmark 鉤子,用於擷取設定檔和捨棄著色器快取,這是在未解鎖裝置上產生基準設定檔或 Macrobenchmark 時所需的 (Ie0a7db/250083467b/253094958) (Ia5171b/231455742)

1.3.0-rc01 版本

2023 年 3 月 8 日

發布 androidx.profileinstaller:profileinstaller:1.3.0-rc01,該版本與上一個 Beta 版沒有差別。查看 1.3.0-rc01 版的修訂項

1.3.0-beta01 版本

2023 年 2 月 8 日

發布 androidx.profileinstaller:profileinstaller:1.3.0-beta011.3.0-beta01 版包含此連結所列的修訂項目。

API 變更

  • 移除處理已壓縮設定檔的支援功能:在啟動期間,開啟及解壓縮程序會導致 CPU 使用率有 0.X 毫秒的迴歸,因此新增診斷功能,方便找出未正確壓縮的基準設定檔 (I86413b/261998144)。

1.3.0-alpha03 版

2023 年 1 月 11 日

發布 androidx.profileinstaller:profileinstaller:1.3.0-alpha031.3.0-alpha03 版包含此連結所列的修訂項目。

修正錯誤

  • 可處理經壓縮或未壓縮的基準設定檔 (Ic61a0)
  • 修正 profileinstaller 資訊清單中的播送註冊資料庫,讓 MacrobenchmarkScope.dropShaderCache() 不再異常終止 (I5c728b/258619948)

1.3.0-alpha02 版本

2022 年 11 月 9 日

發布 androidx.profileinstaller:profileinstaller:1.3.0-alpha02查看 1.3.0-alpha02 版的修訂項

API 變更

  • 為基準新增了掛鉤,用於拖曳著色器快取,確保冷啟動的效能保持一致,特別是在透過暖身疊代的設定檔編譯時。這項更新必須使用 benchmark-macro-junit4:1.2.0-alpha05 以上版本才能評估冷啟動。如需瞭解基準程式庫的 API 變更,請參閱「基準 1.2.0-alpha07」頁面。(Ia5171b/231455742)。

1.3.0-alpha01 版本

2022 年 10 月 24 日

發布 androidx.profileinstaller:profileinstaller:1.3.0-alpha01查看 1.3.0-alpha01 版的修訂項目

API 變更

  • 新增了 ProfileVerifier API,用於在應用程式中檢查是否已編譯、排程或缺少基準設定檔 (I263a4b/246653809)
  • 新增殼層廣播,這可讓 Macrobenchmark 將記憶體內設定檔資料全部清除至磁碟,以包含在基準設定檔產生中。必須使用 Macrobenchmark 程式庫,才能透過 BaselineProfileRule 擷取基準設定檔,並使用 CompilationMode.Partial(warmupIterations) 評估設定檔效能。(Ie0a7db/250083467b/253094958)

1.2.2 版本

1.2.2 版本

2023 年 1 月 11 日

發布 androidx.profileinstaller:profileinstaller:1.2.21.2.2 版包含以下修訂項目。

修正錯誤

  • 可處理經壓縮或未壓縮的基準設定檔 (Ic61a0)

1.2.1 版本

1.2.1 版本

2022 年 12 月 7 日

發布 androidx.profileinstaller:profileinstaller:1.2.1查看 1.2.1 版的修訂項目

新功能

  • 為 S_V2 (API 32) 和 TIRAMISU (API 33) 啟用 profileinstaller (b/254900303)。

1.2.0 版本

1.2.0 版本

2022 年 7 月 27 日

發布 androidx.profileinstaller:profileinstaller:1.2.01.2.0 版包含此連結所列的修訂項目。

自 1.1.0 版以來的重要異動

  • 支援 Android 12 以上版本使用的 ART 設定檔格式。
  • ProfileInstallReceiver 中新增 API,即可在使用基準設定檔時取得更多與 Macrobenchmarks 一致的結果。

1.2.0-rc01 版本

2022 年 6 月 15 日

發布 androidx.profileinstaller:profileinstaller:1.2.0-rc01查看 1.2.0-rc01 版的修訂項目

  • 這個版本與 androidx.profileinstaller:profileinstaller:1.2.0-beta03 相同。

1.2.0-beta03 版本

2022 年 6 月 1 日

發布 androidx.profileinstaller:profileinstaller:1.2.0-beta031.2.0-beta03 版包含此連結所列的修訂項目。

1.2.0-beta02 版

2022 年 5 月 18 日

發布 androidx.profileinstaller:profileinstaller:1.2.0-beta021.2.0-beta02 版包含此連結所列的修訂項目。

  • 無更改,為支援 Compose 1.2.0-beta02 版本所需。

1.2.0-beta01 版本

2022 年 5 月 11 日

發布 androidx.profileinstaller:profileinstaller:1.2.0-beta01查看 1.2.0-beta01 版的修訂項

API 變更

  • ProfileInstallReceiver 中新增 API,即可在使用基準設定檔時取得更多與 Macrobenchmarks 一致的結果。(If2ae5b/215740637)

修正錯誤

  • 嘗試在 Android 12 以上版本使用中繼資料 V_001 格式時,設定檔安裝程式會擲回有用的訊息。(aosp/1978526b/217502387)
  • 設定檔安裝程式現在使用的是 androidx.startup 1.1.1 版本。(aosp/2077099b/229828376)

1.2.0-alpha02 版本

2022 年 1 月 26 日

發布 androidx.profileinstaller:profileinstaller:1.2.0-alpha021.2.0-alpha02 版包含此連結所列的修訂項目。

這個版本與 1.2.0-alpha01 相同。

1.2.0-alpha01 版本

2022 年 1 月 12 日

發布 androidx.profileinstaller:profileinstaller:1.2.0-alpha011.2.0-alpha01 版包含此連結所列的修訂項目。

新功能

  • 支援 Android 12 以上版本使用的 ART 設定檔格式。

1.1.0 版本

1.1.0 版本

2022 年 2 月 9 日

發布 androidx.profileinstaller:profileinstaller:1.1.0查看 1.1.0 版的修訂項

1.1.0-rc01 版本

2021 年 12 月 15 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-rc01,且自 1.1.0-beta04 版以來皆無更新。1.1.0-rc01 版包含此連結所列的修訂項目。

1.1.0-beta04 版

2021 年 12 月 1 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-beta04查看 1.1.0-beta04 版的修訂項

1.1.0-beta03 版本

2021 年 11 月 17 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-beta031.1.0-beta03 版包含此連結所列的修訂項目。

修正錯誤

  • 更新為可支援 Compose 1.1.0-beta03

1.1.0-beta02 版本

2021 年 11 月 3 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-beta02查看 1.1.0-beta02 版的修訂項

修正錯誤

  • 更新為可支援 Compose 1.1.0-beta02

1.1.0-beta01 版本

2021 年 10 月 27 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-beta011.1.0-beta01 版包含此連結所列的修訂項目。

  • 自 1.1.0-alpha07 起沒有變更。

1.1.0-alpha07 版本

2021 年 10 月 13 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-alpha07查看 1.1.0-alpha07 版的修訂項

新功能

  • 支援 Android N 的 Profm 功能

1.1.0-alpha06 版本

2021 年 9 月 29 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-alpha06查看 1.1.0-alpha06 版的修訂項

修正錯誤

  • 修正 N、O 和 O_MR1 上的 profileinstaller 轉碼問題。(I12d75)。

1.1.0-alpha05 版本

2021 年 9 月 15 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-alpha05查看 1.1.0-alpha05 版的修訂項

修正錯誤

  • 修正 multidex APK 的 Android Nougat 和 Android Oreo 設定檔轉碼問題。

1.1.0-alpha04 版本

2021 年 9 月 1 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-alpha041.1.0-alpha04 版包含此連結所列的修訂項目。

修正錯誤

  • 修正 ProfileInstaller,方便應用程式使用基準設定檔透過 CompilationMode.BaselineProfile 執行 MacroBenchmarks。(I42657b/196074999)

1.1.0-alpha03 版本

2021 年 8 月 18 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-alpha031.1.0-alpha03 版本包含以下修訂項目。

修正錯誤

  • 將 profileinstaller 略過行為變更為將 PackageInfo.lastUpdatedTime 記錄在應用程式檔案目錄中的檔案裡,並在下次執行安裝設定檔之前進行比較 (Ib93d1)
  • 調整 P、Q、R 裝置的設定檔格式,以符合 ART 規定 (I84e89)

1.1.0-alpha02 版本

2021 年 8 月 4 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-alpha02查看 1.1.0-alpha02 版的修訂項

更新為可支援 Compose 1.1.0-alpha01。

1.1.0-alpha01 版本

2021 年 7 月 21 日

發布 androidx.profileinstaller:profileinstaller:1.1.0-alpha011.1.0-alpha01 版包含以下修訂項目。

修正錯誤

  • 修正在某些情況下會觸發嚴格模式的錯誤。

1.0 版本

1.0.4 版本

2021 年 10 月 13 日

發布 androidx.profileinstaller:profileinstaller:1.0.41.0.4 版包含此連結所列的修訂項目。

  • 更新為可支援 Compose 1.0.4

1.0.3 版本

2021 年 9 月 29 日

發布 androidx.profileinstaller:profileinstaller:1.0.31.0.3 版包含此連結所列的修訂項目。

  • 更新為可支援 Compose 1.0.3

1.0.2 版本

2021 年 9 月 1 日

發布 androidx.profileinstaller:profileinstaller:1.0.21.0.2 版包含此連結所列的修訂項目。

修正錯誤

  • 為 P、Q、R 裝置新增設定檔轉碼。這項變更表示這些裝置會將設定檔轉碼,確保寫下的設定檔隨時可供 ART 使用。以往在這些平台上,系統會略過轉碼,有時這會造成 ART 無法處理來源設定檔。開發人員 API 沒有任何變更。

1.0.1 版本

2021 年 8 月 4 日

發布 androidx.profileinstaller:profileinstaller:1.0.11.0.1 版包含以下修訂項目。

更新為可支援 Compose 1.0.1。

1.0.0 版本

2021 年 7 月 28 日

發布 androidx.profileinstaller:profileinstaller:1.0.01.0.0 版包含此連結所列的修訂項目。

1.0.0 的主要功能

設定檔安裝程式是新的程式庫,可讓程式庫和應用程式定義「設定檔規則」,並將 ART 設定檔資訊與 APK 組合在一起,這個程式庫會在應用程式啟動後安裝這些設定檔。這可以用來改善應用程式效能。

如要進一步瞭解這些設定檔規則是什麼,其運作方式又是如何,請參閱 1.0.0-beta01 的詳細版本資訊。

1.0.0-rc02 版

2021 年 7 月 14 日

發布 androidx.profileinstaller:profileinstaller:1.0.0-rc02查看 1.0.0-rc02 版的修訂項

1.0.0-rc01 版

2021 年 7 月 1 日

發布 androidx.profileinstaller:profileinstaller:1.0.0-rc011.0.0-rc01 版包含以下修訂項目。

此為 RC 版本,沒有變更 Beta 版任何內容。

1.0.0-beta01 版

2021 年 6 月 16 日

androidx.profileinstaller:profileinstaller:1.0.0-beta01 發布。1.0.0-beta01 版包含此連結所列的修訂項目。

程式庫用途

設定檔安裝程式是一種新的程式庫,可讓程式庫和應用程式定義「設定檔規則」,並將 ART 設定檔資訊與 APK 組合起來,這種程式庫會在應用程式啟動後安裝這些設定檔。這可以用來改善應用程式效能。

這個設定檔安裝作業是由 androidx.startup 程式庫完成。無論原因為何,只要使用者想停用設定檔安裝功能,都可以修改資訊清單將其移除:


       <provider
           android:name="androidx.startup.InitializationProvider"
           android:authorities="${applicationId}.androidx-startup"
           android:exported="false"
           tools:node="merge">
           <meta-data android:name="androidx.profileinstaller.ProfileInstallerInitializer"
                     tools:node="remove" />
       </provider>

如果您的應用程式啟動規定較複雜,您希望使用 ProfileInstaller.writeProfile API 手動觸發安裝作業,這種停用方法就能派上用場。

什麼是設定檔規則?

  • 程式庫的設定檔規則在位於 src/main 或同等目錄中的文字檔 baseline-prof.txt 內進行指定。該檔案會每行指定一個規則,這裡的規則是指對應至程式庫方法或類別的模式。這些規則所用語法是人類可讀形式的 ART 設定檔格式的超集,使用 adb shell profman --dump-classes-and-methods ... 時會用到這類格式。這些規則會採用兩種形式之一來指定方法或類別。

  • 方法規則將採用以下模式:

    <FLAGS><CLASS_DESCRIPTOR>-><METHOD_SIGNATURE>
    
  • 類別規則將採用以下模式:

    <CLASS_DESCRIPTOR>
    
  • 此處的 <FLAGS>HSP 之中的一或多個字元,用於指出這個方法應標記為「Hot」、「Startup」或「Post Startup」。

  • <CLASS_DESCRIPTOR> 是指定方法所屬的類別描述元。舉例來說,androidx.compose.runtime.SlotTable 類別的描述元是 Landroidx/compose/runtime/SlotTable;

  • <METHOD_SIGNATURE> 是方法的簽名,含有該方法的名稱、參數類型和傳回類型。舉例來說,LayoutNode 上的 fun isPlaced(): Boolean 方法含有 isPlaced()Z 簽名。

  • 這些模式可包含萬用字元 (***?),以便讓單一規則涵蓋多種方法或類別。

規則有何作用?

  • 方法中如果帶有 H 標記,表示這個方法是「Hot」方法,應該預先完成編譯。

  • 方法中如果帶有 S 標記,表示這是系統會在啟動時呼叫的方法,應該預先完成編譯,以免啟動時耗費資源處理編譯作業及解析方法。

  • 方法中如果帶有 P 標記,表示這是系統在啟動之後才會呼叫的方法。

  • 如果類別顯示在這個檔案中,表示系統會在啟動期間使用該類別,因此應該要事先在堆積中分配該類別,以免耗費載入類別的成本。

服務簡介

  • 程式庫可以定義這些規則,並會包裝於 AAR 構件中。當建構包含這些構件的 APK 時,這些規則將合併在一起,合併後的規則會用於建構該 APK 專用的精簡二進制 ART 設定檔。當 APK 安裝在裝置上時,ART 便可以利用這個設定檔預先編譯特定應用程式子集,藉此提高應用程式效能,特別是首次執行的效能。請注意,這項設定對於可進行偵錯的應用程式不會產生任何影響。

  • 規則檔案應命名為 baseline-prof.txt,並放置在主要來源集的根目錄中 (該檔案應屬於您 AndroidManifset.xml 檔案的同層級檔案)

  • 目前您必須使用 Android Gradle 外掛程式 7.0 以上版本才能運用這些檔案,而且您的 gradle.properties 中必須設有旗標才能啟用:

    # Enable adding baseline-prof.txt files to AAR artifacts, and binary profiles to APKs
    android.experimental.enableArtProfiles=true
    

設定檔必須保持平衡

  • 妥善設計的設定檔會正確優先處理啟動路徑中的重要方法和類別,並帶來最佳效能,但如果在設定檔中加入過多的方法或類別,最終可能會對記憶體用量和磁碟用量造成負面影響,因此建議在定義自己的設定檔規則時,先從保守的做法開始。