ProfileInstaller
Latest Update | Stable Release | Release Candidate | Beta Release | Alpha Release |
---|---|---|---|---|
August 21, 2024 | 1.3.1 | - | 1.4.0-beta01 | - |
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.3.1" }
Kotlin
dependencies { implementation("androidx.profileinstaller:profileinstaller:1.3.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.
See the Issue Tracker documentation for more information.
Version 1.4
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
inProfileInstallReceiver
. (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 usingCompilationMode.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
version1.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 usingCompilationMode.Partial(warmupIterations)
. (Ie0a7d, b/250083467, b/253094958)
Version 1.2.2
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
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
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 withMacrobenchmarks
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 withMacrobenchmarks
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
version1.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
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 usingCompilationMode.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
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.
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 thesrc/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 usingadb 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 charactersH
,S
, andP
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 classandroidx.compose.runtime.SlotTable
would have a descriptor ofLandroidx/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 methodfun isPlaced(): Boolean
onLayoutNode
has the signatureisPlaced()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 yourAndroidManifset.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.