ProfileInstaller

Enables libraries to prepopulate ahead of time compilation traces to be read by ART.

Latest Update	Stable Release	Release Candidate	Beta Release	Alpha Release
October 2, 2024	1.4.1	-	-	-

Declaring dependencies

To add a dependency on ProfileInstaller, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

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

Kotlin

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

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.4

Version 1.4.1

October 2, 2024

androidx.profileinstaller:profileinstaller:1.4.1 is released. Version 1.4.1 contains these commits.

Bug Fixes

Fixed support for multi-process Baseline Profile recording by signaling multiple processes sequentially. This fix requires both updating to androidx.benchmark:benchmark-macro:1.4.0-alpha02 in your macrobenchmark/baseline profile module and androidx.profileinstaller:profileinstaller:1.4.1 in the app. (I0f519, b/366231469)

Version 1.4.0

September 18, 2024

androidx.profileinstaller:profileinstaller:1.4.0 is released. Version 1.4.0 contains these commits.

Important changes since 1.3.0

ProfileInstaller now supports capturing/installing profiles on API 35+. Updates to ProfileInstaller should no longer be required for platform version updates. (6f9f6fa)
Fixes crash when dropping shaders on Android U (API 34), as well as on emulators. (I031ca, b/274314544)
Fix method flag transcoding in the V_015S profile format. (aosp/2906631, aosp/2847740)

Version 1.4.0-rc01

September 4, 2024

androidx.profileinstaller:profileinstaller:1.4.0-rc01 is released with no changes from the last beta release. Version 1.4.0-rc01 contains these commits.

Version 1.4.0-beta01

August 21, 2024

androidx.profileinstaller:profileinstaller:1.4.0-beta01 is released with no changes from the last alpha. Version 1.4.0-beta01 contains these commits.

Version 1.4.0-alpha02

August 7, 2024

androidx.profileinstaller:profileinstaller:1.4.0-alpha02 is released. Version 1.4.0-alpha02 contains these commits.

New Features

Added api 35 support to Profile Installer. (6f9f6fa)

Bug Fixes

Removed manual outlining of access to new platform APIs since this happens automatically via API modeling when using R8 with AGP 7.3 or later (e.g. R8 version 3.3) and for all builds when using AGP 8.1 or later (e.g. D8 version 8.1). Clients who are not using AGP are advised to update to D8 version 8.1 or later. See this article for more details. (If6b4c, b/345472586)

Version 1.4.0-alpha01

February 7, 2024

androidx.profileinstaller:profileinstaller:1.4.0-alpha01 is released. Version 1.4.0-alpha01 contains these commits.

Bug Fixes

Added error code for no profile embedded to profile verifier. (Ifb109, b/313928520)
Fixes crash when dropping shaders on Android U (API 34), as well as on emulators. (I031ca, b/274314544)
Enabled support for Android U in profile installer. (Iaf177)
Fixed profile installer on Android U failing due to current profile not created empty when process starts. (Ie3899)
Fix method bitmap transcoding in the V_015S profile format. (aosp/2906631) and (aosp/2847740)

Version 1.3

Version 1.3.1

May 3, 2023

androidx.profileinstaller:profileinstaller:1.3.1 is released. Version 1.3.1 contains these commits.

Bug Fixes

Enabled support for Android U in profile installer (Iaf177)
Fixed profile installer on Android U failing due to current profile not created empty when process starts. (Ie3899)

Version 1.3.0

March 22, 2023

androidx.profileinstaller:profileinstaller:1.3.0 is released. Version 1.3.0 contains these commits.

Important changes since 1.2.0

Fixed a NullPointerException in ProfileInstallReceiver. (b/243851384)
Added ProfileVerifier api to check from within the app if a baseline profile has been compiled, scheduled, or is missing (I263a4, b/246653809)
Adds a new shell broadcast that enables Macrobenchmark to fully flush in-memory profile data to disk, to be included in baseline profile generation. This is required to use the macrobenchmark library to capture baseline profiles with BaselineProfileRule, and evaluate profile performance using CompilationMode.Partial(warmupIterations).
Added a diagnostic code to detect compressed baseline profiles. Compressed baseline profiles cannot be installed by Profileinstaller in Macrobenchmarks or in production due to CPU overhead, and should be avoided when building your app by updating either to Studio/AGP Electric Eel or bundletool version 1.13.1(I86413, b/261998144)
Added hooks for macrobenchmark to capture profiles and drop shader cache, which are required for generating Baseline Profiles or macrobenchmarking on unrooted devices (Ie0a7d, b/250083467, b/253094958) (Ia5171, b/231455742)

Version 1.3.0-rc01

March 8, 2023

androidx.profileinstaller:profileinstaller:1.3.0-rc01 is released with no changes since the last beta. Version 1.3.0-rc01 contains these commits.

Version 1.3.0-beta01

February 8, 2023

androidx.profileinstaller:profileinstaller:1.3.0-beta01 is released. Version 1.3.0-beta01 contains these commits.

API Changes

Removes support for handling compressed profiles - opening and decompressing leads to a 10s of ms regression in CPU utilization during startup, so instead added a diagnostic to discover incorrectly compressed baseline profiles. (I86413, b/261998144)

Version 1.3.0-alpha03

January 11, 2023

androidx.profileinstaller:profileinstaller:1.3.0-alpha03 is released. Version 1.3.0-alpha03 contains these commits.

Bug Fixes

Enables handling of compressed or uncompressed baseline profiles (Ic61a0)
Fix MacrobenchmarkScope.dropShaderCache() to no longer crash by fixing broadcast registry in profileinstaller manifest (I5c728, b/258619948)

Version 1.3.0-alpha02

November 9, 2022

androidx.profileinstaller:profileinstaller:1.3.0-alpha02 is released. Version 1.3.0-alpha02 contains these commits.

API Changes

Added a hook for benchmarks to drop the shader cache, to ensure consistent performance for cold startups, especially when compiling with profiles from warmup iterations. This update is required to measure cold startups using benchmark-macro-junit4:1.2.0-alpha05 or later. For Benchmark library’s API changes, please refer to Benchmark 1.2.0-alpha07 page. (Ia5171, b/231455742)

Version 1.3.0-alpha01

October 24, 2022

androidx.profileinstaller:profileinstaller:1.3.0-alpha01 is released. Version 1.3.0-alpha01 contains these commits.

API Changes

Added ProfileVerifier api to check from within the app if a baseline profile has been compiled, scheduled, or is missing (I263a4, b/246653809)
Adds a new shell broadcast that enables Macrobenchmark to fully flush in-memory profile data to disk, to be included in baseline profile generation. This is required to use the macrobenchmark library to capture baseline profiles with BaselineProfileRule, and evaluate profile performance using CompilationMode.Partial(warmupIterations). (Ie0a7d, b/250083467, b/253094958)

Version 1.2.2

January 11, 2023

androidx.profileinstaller:profileinstaller:1.2.2 is released. Version 1.2.2 contains these commits.

Bug Fixes

Enables handling of compressed or uncompressed baseline profiles (Ic61a0)

Version 1.2.1

December 7, 2022

androidx.profileinstaller:profileinstaller:1.2.1 is released. Version 1.2.1 contains these commits.

New Features

Enable profileinstaller for S_V2 (API 32) and TIRAMISU (API 33) (b/254900303).

Version 1.2.0

July 27, 2022

androidx.profileinstaller:profileinstaller:1.2.0 is released. Version 1.2.0 contains these commits.

Important changes since 1.1.0

Added support for the ART profile format used on Android 12 and going forward.
Add new APIs in ProfileInstallReceiver to get more consistent results with Macrobenchmarks when using baseline profiles.

Version 1.2.0-rc01

June 15, 2022

androidx.profileinstaller:profileinstaller:1.2.0-rc01 is released. Version 1.2.0-rc01 contains these commits.

This version is identical to androidx.profileinstaller:profileinstaller:1.2.0-beta03.

Version 1.2.0-beta03

June 1, 2022

androidx.profileinstaller:profileinstaller:1.2.0-beta03 is released. Version 1.2.0-beta03 contains these commits.

Version 1.2.0-beta02

May 18, 2022

androidx.profileinstaller:profileinstaller:1.2.0-beta02 is released. Version 1.2.0-beta02 contains these commits.

No changes, needed to support Compose 1.2.0-beta02 versions.

Version 1.2.0-beta01

May 11, 2022

androidx.profileinstaller:profileinstaller:1.2.0-beta01 is released. Version 1.2.0-beta01 contains these commits.

API Changes

Add new APIs in ProfileInstallReceiver to get more consistent results with Macrobenchmarks when using baseline profiles. (If2ae5, b/215740637)

Bug Fixes

Profile Installer throws a helpful message when trying to use metadata V_001 format on Android 12 and above. (aosp/1978526, b/217502387)
Profile Installer now uses androidx.startup version 1.1.1. (aosp/2077099, b/229828376)

Version 1.2.0-alpha02

January 26, 2022

androidx.profileinstaller:profileinstaller:1.2.0-alpha02 is released. Version 1.2.0-alpha02 contains these commits.

This version is identical to 1.2.0-alpha01.

Version 1.2.0-alpha01

January 12, 2022

androidx.profileinstaller:profileinstaller:1.2.0-alpha01 is released. Version 1.2.0-alpha01 contains these commits.

New Features

Add support for the ART profile format used on Android 12 and going forward.

Version 1.1.0

February 9, 2022

androidx.profileinstaller:profileinstaller:1.1.0 is released. Version 1.1.0 contains these commits.

Version 1.1.0-rc01

December 15, 2021

androidx.profileinstaller:profileinstaller:1.1.0-rc01 is released with no updates since 1.1.0-beta04. Version 1.1.0-rc01 contains these commits.

Version 1.1.0-beta04

December 1, 2021

androidx.profileinstaller:profileinstaller:1.1.0-beta04 is released. Version 1.1.0-beta04 contains these commits.

Version 1.1.0-beta03

November 17, 2021

androidx.profileinstaller:profileinstaller:1.1.0-beta03 is released. Version 1.1.0-beta03 contains these commits.

Bug Fixes

Updated to support Compose 1.1.0-beta03

Version 1.1.0-beta02

November 3, 2021

androidx.profileinstaller:profileinstaller:1.1.0-beta02 is released. Version 1.1.0-beta02 contains these commits.

Bug Fixes

Updated to support Compose 1.1.0-beta02

Version 1.1.0-beta01

October 27, 2021

androidx.profileinstaller:profileinstaller:1.1.0-beta01 is released. Version 1.1.0-beta01 contains these commits.

No changes since 1.1.0-alpha07.

Version 1.1.0-alpha07

October 13, 2021

androidx.profileinstaller:profileinstaller:1.1.0-alpha07 is released. Version 1.1.0-alpha07 contains these commits.

New Features

Added support for profm on Android N

Version 1.1.0-alpha06

September 29, 2021

androidx.profileinstaller:profileinstaller:1.1.0-alpha06 is released. Version 1.1.0-alpha06 contains these commits.

Bug Fixes

Fix profileinstaller transcoding issues on N, O, and O_MR1. (I12d75)

Version 1.1.0-alpha05

September 15, 2021

androidx.profileinstaller:profileinstaller:1.1.0-alpha05 is released. Version 1.1.0-alpha05 contains these commits.

Bug Fixes

Fixed Android Nougat and Android Oreo profile transcoding for multidex apks.

Version 1.1.0-alpha04

September 1, 2021

androidx.profileinstaller:profileinstaller:1.1.0-alpha04 is released. Version 1.1.0-alpha04 contains these commits.

Bug Fixes

Fix ProfileInstaller to make it easier for apps using baseline profiles to run MacroBenchmarks using CompilationMode.BaselineProfile. (I42657, b/196074999)

Version 1.1.0-alpha03

August 18, 2021

androidx.profileinstaller:profileinstaller:1.1.0-alpha03 is released. Version 1.1.0-alpha03 contains these commits.

Bug Fixes

Change profileinstaller skip behavior to log the PackageInfo.lastUpdatedTime in a file in the app's files directory and compare it prior to installing the profile on the next run. (Ib93d1)
Adjust profile format on P, Q, R devices to conform to ART requirements (I84e89)

Version 1.1.0-alpha02

August 4, 2021

androidx.profileinstaller:profileinstaller:1.1.0-alpha02 is released. Version 1.1.0-alpha02 contains these commits.

Updated to be compatible with Compose 1.1.0-alpha01.

Version 1.1.0-alpha01

July 21, 2021

androidx.profileinstaller:profileinstaller:1.1.0-alpha01 is released. Version 1.1.0-alpha01 contains these commits.

Bug Fixes

Fixed bug that would trigger strict mode in some circumstances.

Version 1.0

Version 1.0.4

October 13, 2021

androidx.profileinstaller:profileinstaller:1.0.4 is released. Version 1.0.4 contains these commits.

Updated to support Compose 1.0.4

Version 1.0.3

September 29, 2021

androidx.profileinstaller:profileinstaller:1.0.3 is released. Version 1.0.3 contains these commits.

Updated to support Compose 1.0.3

Version 1.0.2

September 1, 2021

androidx.profileinstaller:profileinstaller:1.0.2 is released. Version 1.0.2 contains these commits.

Bug Fixes

Added profile transcoding for P, Q, R devices. This change means that these devices will transcode the profile, ensuring that the written profile is always usable by ART. Previously transcoding would be skipped on these platforms, which sometimes lead ART to be unable to process the source profile. No changes to developer APIs.

Version 1.0.1

August 4, 2021

androidx.profileinstaller:profileinstaller:1.0.1 is released. Version 1.0.1 contains these commits.

Updated to be compatible with Compose 1.0.1.

Version 1.0.0

July 28, 2021

androidx.profileinstaller:profileinstaller:1.0.0 is released. Version 1.0.0 contains these commits.

Major features of 1.0.0

Profile installer is a new library that allows libraries and applications to define “Profile Rules” and bundle ART profile information with an APK, and this library will install those profiles after application launch. This can be utilized to improve application performance.

Please see the detailed release notes at 1.0.0-beta01 for more information on what these profile rules are and how they work.

Version 1.0.0-rc02

July 14, 2021

androidx.profileinstaller:profileinstaller:1.0.0-rc02 is released. Version 1.0.0-rc02 contains these commits.

Version 1.0.0-rc01

July 1, 2021

androidx.profileinstaller:profileinstaller:1.0.0-rc01 is released. Version 1.0.0-rc01 contains these commits.

This is a RC release with no changes from beta.

Version 1.0.0-beta01

June 16, 2021

androidx.profileinstaller:profileinstaller:1.0.0-beta01 is released. Version 1.0.0-beta01 contains these commits.

Library Purpose

This profile installation is done with the androidx.startup library. If for any reason one would like to disable profile installation, they can modify the manifest to remove it:


       <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>

This is especially useful if your app has nontrivial startup requirements and you would like to trigger the profile installation manually using the ProfileInstaller.writeProfile API.

What are profile rules?

Profile rules for a library are specified in a text file baseline-prof.txt located in the src/main or equivalent directory. The file specifies a rule per line, where a rule in this case is a pattern for matching to methods or classes in the library. The syntax for these rules is a superset of the human-readable ART profile format that is used when using adb shell profman --dump-classes-and-methods .... These rules take one of two forms to target either methods or classes.

A method rule will have the following pattern:

<FLAGS><CLASS_DESCRIPTOR>-><METHOD_SIGNATURE>

And a class rule will have the following pattern:
```
<CLASS_DESCRIPTOR>
```
Here <FLAGS> is one or more of the characters H, S, and P to indicate whether or not this method should be flagged as "Hot", "Startup", or "Post Startup".
The <CLASS_DESCRIPTOR> is the descriptor for the class that the targeted method belongs to. For example, the class androidx.compose.runtime.SlotTable would have a descriptor of Landroidx/compose/runtime/SlotTable;.
The <METHOD_SIGNATURE> is the signature of the method, and includes the name, parameter types, and return types of the method. For example, the method fun isPlaced(): Boolean on LayoutNode has the signature isPlaced()Z.
These patterns can have wildcards (**, *, and ?) in order to have a single rule encompass multiple methods or classes.

What do the rules do?

A method that has the flag H indicates that this method is a "hot" method, and should be compiled ahead of time.
A method that has the flag S indicates that it is a method which is called at startup, and should be compiled ahead of time to avoid the cost of compilation and interpreting the method at startup time.
A method that has the flag P indicates that it is a method which is called after startup.
A class that is present in this file indicates that it is used during startup and should be pre-allocated in the heap to avoid the cost of class loading.

How does this work?

Libraries can define these rules which will be packaged in AAR artifacts. When an APK is then built which includes these artifacts, these rules are merged together and the merged rules are used to build a compact binary ART profile that is specific to the APK. ART can then leverage this profile when the APK is installed on devices in order to ahead-of-time compile a specific subset of the application to improve the performance of the application, especially the first run. Note that this will have no effect on debuggable applications.
Rule files should be named baseline-prof.txt and placed in the root directory of your main source set (it should be a sibling file to your AndroidManifset.xml file)
Currently these files will only be utilized if you are using Android Gradle Plugin 7.0+, and is currently only enabled with a flag in your gradle.properties:
```
# Enable adding baseline-prof.txt files to AAR artifacts, and binary profiles to APKs
android.experimental.enableArtProfiles=true
```

Profiles require a balance

Properly crafted profiles which correctly prioritize methods and classes that will be in the startup path and performance critical will yield the best results, however including too many methods or classes in profiles can end up having a net negative effect in terms of memory consumption and disk usage, so it is recommended to start conservatively if defining your own profile rules.