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 execution or scheduling of dexopt operations by ART Service is 112**not** triggered by an app's running or launch status. 113 114Warning: The sections below describe the default behavior in each scenario. Note 115that the list of apps to dexopt and the compiler filter, as well as other 116options, can be customized by partners through system properties, APIs, etc. 117 118### On the very first boot / the first boot after an OTA update 119 120On the very first boot / the first boot after an OTA update, ART Service only 121dexopts primary dex files of all apps with the "verify" compiler filter. 122 123If `pm.dexopt.downgrade_after_inactive_days` is set, during the first boot after 124an OTA update, ART Service only dexopts apps used within the last given number of 125days. 126 127Note: It doesn't dexopt secondary dex files or use the "speed-profile" filter 128because doing so may block the boot for too long. 129 130In practice, ART Service does nothing for most of the apps. Because the default 131compiler filter is "verify", which tolerates dependency mismatches, apps with 132usable VDEX files generally don't need to be re-dexopted. This includes: 133 134- apps on the **system partitions** that have artifacts generated by 135 dexpreopt, even if the dependencies (class loader contexts) are not properly 136 configured. 137- apps on the **data partition** that have been dexopted in other scenarios 138 (install, background dexopt, etc.), even though their dependencies 139 (bootclasspath, boot images, and class loader contexts) have probably 140 changed. 141 142In other words, in this scenario, ART Service mostly only dexopts: 143 144- apps in APEXes, because they are not supported by dexpreopt 145- apps on the system partitions with dexpreopt disabled 146- apps forced to have "speed-profile" or "speed" compiler filters (the system UI 147 and the launcher) but dexpreopted with wrong dependencies 148 149### On the first boot after a mainline update 150 151On the first boot after a mainline update, ART Service dexopts the primary dex 152files of the system UI and the launcher. It uses the compiler filter specified 153by `dalvik.vm.systemuicompilerfilter` for the system UI, and uses the 154"speed-profile" compiler filter for the launcher. 155 156Note: It only dexopts those two apps because they are important to user 157experience. 158 159Note: ART Service cannot use the "speed-profile" compiler filter for the system 160UI because the system UI is dexpreopted using the "speed" compiler filter and 161therefore it's never JITed and as a result there is no profile collected on the 162device to use, though this may change in the future. For now, we strongly 163recommend to set `dalvik.vm.systemuicompilerfilter` to "speed". 164 165### During app installation 166 167During app installation, ART Service dexopts the primary dex files of the app. 168If the app is installed along with a DM file that contains a profile (known as a 169*cloud profile*), it uses the "speed-profile" compiler filter. Otherwise, it 170uses the "verify" compiler filter. 171 172Note: If the APK is uncompressed and aligned, and it is installed along with a 173DM file that only contains a VDEX file (but not a profile), no dexopt will be 174performed because the compiler filter will be "verify" and the VDEX file is 175satisfactory. 176 177Note: There is no secondary dex file present during installation. 178 179### When the device is idle and charging 180 181ART Service has a job called *background dexopt job* managed by Job Scheduler. 182It is triggered daily when the device is idle and charging. During the job 183execution, it dexopts primary dex files and secondary dex files of all apps with 184the "speed-profile" compiler filter. 185 186If `pm.dexopt.downgrade_after_inactive_days` is set, ART Service only dexopts 187apps used within the last given number of days, and it downgrades other apps 188(with the compilation reason `inactive`). 189 190The job is cancellable. When the device is no longer idle or charging, Job 191Scheduler cancels the job. 192 193### When requested through commandline 194 195ART Service can be invoked by commands (`pm compile`, `pm bg-dexopt-job`, and 196`pm art dexopt-packages`). Run `pm help` to see the usages and the differences 197between them. 198