1# ART Service 2 3Warning: The contents in this doc can become stale while the code evolves. 4 5ART Service manages dexopt artifacts of apps. With ART Service, you can dexopt 6apps, query their dexopt status (the compiler filter, the compilation reason, 7whether the dexopt artifacts are up-to-date, etc.), and delete dexopt artifacts. 8 9Note: ART Service is introduced in Android U. Prior to ART Service, dexopt 10artifacts were managed by Package Manager with a legacy implementation. The 11legacy implementation will be removed in Android V. This doc only describes 12ART Service, not the legacy implementation. 13 14## Concepts 15 16### Primary dex vs. secondary dex 17 18ART Service dexopts both primary dex files and secondary dex files of an app. 19 20A primary dex file refers to the base APK or a split APK of an app. It's 21installed by Package Manager or shipped as a part of the system image, and it's 22loaded by Framework on app startup. 23 24A secondary dex file refers to an APK or JAR file that an app adds to its own 25data directory and loads dynamically. 26 27Note: Strictly speaking, an APK/JAR file is not a DEX file. It is a ZIP file 28that contain one or more DEX files. However, it is called a *dex file* 29conventionally. 30 31### Compiler filters 32 33See 34[Compilation options](https://source.android.com/docs/core/runtime/configure#compilation_options). 35 36### Priority classes 37 38A priority class indicates the priority of an operation. The value affects the 39resource usage and the process priority. A higher value may result in faster 40execution but may consume more resources and compete for resources with other 41processes. 42 43Options are (from the highest to the lowest): 44 45- `PRIORITY_BOOT`: Indicates that the operation blocks boot. 46- `PRIORITY_INTERACTIVE_FAST`: Indicates that a human is waiting on the result 47 and the operation is more latency sensitive than usual. It's typically used 48 when the user is entirely blocked, such as for restoring from cloud backup. 49- `PRIORITY_INTERACTIVE`: Indicates that a human is waiting on the result. 50 (E.g., for app install) 51- `PRIORITY_BACKGROUND`: Indicates that the operation runs in background. 52 53### Compilation reasons 54 55A compilation reason is a string that determines the default 56[compiler filter](#compiler-filters) and the default 57[priority class](#priority-classes) of an operation. 58 59It's also passed to `dex2oat` and stored in the header of the OAT file, for 60debugging purposes. To retrieve the compilation reason from an OAT file, run 61 62``` 63pm art dump <package-name> 64``` 65 66or 67 68``` 69oatdump --header-only --oat-file=<odex-filename> | grep 'compilation-reason =' 70``` 71 72It can be either a predefined value in 73`art/libartservice/service/java/com/android/server/art/ReasonMapping.java` 74or a custom string. If the value is a custom string, the priority class and the 75compiler filter must be explicitly set. 76 77Each predefined value corresponds to one of the 78[dexopt scenarios](#dexopt-scenarios). 79 80#### The `-dm` suffix 81 82Sometimes, you may see the `-dm` suffix in an OAT file, such as `install-dm`. 83However, the `-dm` suffix is **not** a part of the compilation reason. It's 84appended to the compilation reason to indicate that a DM (`.dm`) file is passed 85to `dex2oat` during dexopt for **app install**. 86 87Note: ART Service also passes the DM file to `dex2oat` in other scenarios, such 88as background dexopt, but for compatibility reasons, the `-dm` suffix is not 89appended in those scenarios. 90 91Note: The `-dm` suffix does **not** imply anything in the DM file being used by 92`dex2oat`. The augmented compilation reason can still be `install-dm` even if 93the DM file is empty or if `dex2oat` leaves all contents of the DM file unused. 94That would only happen if there's a bug, like the wrong DM file being passed. 95 96## Dexopt scenarios 97 98At a high level, ART Service dexopts apps in the following scenarios: 99 100- the device is on the very first boot (Compilation reason: `first-boot`) 101- the device is on the first boot after an OTA update (Compilation reason: 102 `boot-after-ota`) 103- the device is on the first boot after a mainline update (Compilation reason: 104 `boot-after-mainline-update`) 105- an app is being installed (Compilation reason: `install` / `install-fast` 106 / etc.) 107- the device is idle and charging (Compilation reason: `bg-dexopt` / 108 `inactive`) 109- requested through commandline (Compilation reason: `cmdline`) 110 111Warning: The sections below describe the default behavior in each scenario. Note 112that the list of apps to dexopt and the compiler filter, as well as other 113options, can be customized by partners through system properties, APIs, etc. 114 115### On the very first boot / the first boot after an OTA update 116 117On the very first boot / the first boot after an OTA update, ART Service only 118dexopts primary dex files of all apps with the "verify" compiler filter. 119 120If `pm.dexopt.downgrade_after_inactive_days` is set, during the first boot after 121an OTA update, ART Service only dexopts apps used within the last given number of 122days. 123 124Note: It doesn't dexopt secondary dex files or use the "speed-profile" filter 125because doing so may block the boot for too long. 126 127In practice, ART Service does nothing for most of the apps. Because the default 128compiler filter is "verify", which tolerates dependency mismatches, apps with 129usable VDEX files generally don't need to be re-dexopted. This includes: 130 131- apps on the **system partitions** that have artifacts generated by 132 dexpreopt, even if the dependencies (class loader contexts) are not properly 133 configured. 134- apps on the **data partition** that have been dexopted in other scenarios 135 (install, background dexopt, etc.), even though their dependencies 136 (bootclasspath, boot images, and class loader contexts) have probably 137 changed. 138 139In other words, in this scenario, ART Service mostly only dexopts: 140 141- apps in APEXes, because they are not supported by dexpreopt 142- apps on the system partitions with dexpreopt disabled 143- apps forced to have "speed-profile" or "speed" compiler filters (the system UI 144 and the launcher) but dexpreopted with wrong dependencies 145 146### On the first boot after a mainline update 147 148On the first boot after a mainline update, ART Service dexopts the primary dex 149files of the system UI and the launcher. It uses the compiler filter specified 150by `dalvik.vm.systemuicompilerfilter` for the system UI, and uses the 151"speed-profile" compiler filter for the launcher. 152 153Note: It only dexopts those two apps because they are important to user 154experience. 155 156Note: ART Service cannot use the "speed-profile" compiler filter for the system 157UI because the system UI is dexpreopted using the "speed" compiler filter and 158therefore it's never JITed and as a result there is no profile collected on the 159device to use, though this may change in the future. For now, we strongly 160recommend to set `dalvik.vm.systemuicompilerfilter` to "speed". 161 162### During app installation 163 164During app installation, ART Service dexopts the primary dex files of the app. 165If the app is installed along with a DM file that contains a profile (known as a 166*cloud profile*), it uses the "speed-profile" compiler filter. Otherwise, it 167uses the "verify" compiler filter. 168 169Note: If the APK is uncompressed and aligned, and it is installed along with a 170DM file that only contains a VDEX file (but not a profile), no dexopt will be 171performed because the compiler filter will be "verify" and the VDEX file is 172satisfactory. 173 174Note: There is no secondary dex file present during installation. 175 176### When the device is idle and charging 177 178ART Service has a job called *background dexopt job* managed by Job Scheduler. 179It is triggered when the device is idle and charging. During the job execution, 180it dexopts primary dex files and secondary dex files of all apps with the 181"speed-profile" compiler filter. 182 183If `pm.dexopt.downgrade_after_inactive_days` is set, ART Service only dexopts 184apps used within the last given number of days, and it downgrades other apps 185(with the compilation reason `inactive`). 186 187The job is cancellable. When the device is no longer idle or charging, Job 188Scheduler cancels the job. 189 190### When requested through commandline 191 192ART Service can be invoked by commands (`pm compile`, `pm bg-dexopt-job`, and 193`pm art dexopt-packages`). Run `pm help` to see the usages and the differences 194between them. 195