ProfileInstaller

  
Enables libraries to prepopulate ahead of time compilation traces to be read by ART.
Latest Update Current Stable Release Next Release Candidate Beta Release Alpha Release
October 27, 2021 1.0.4 - 1.1.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.1.0-beta01"
}

Kotlin

dependencies {
    implementation("androidx.profileinstaller:profileinstaller:1.1.0-beta01")
}

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

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

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