1# Build-time system feature support 2 3## Overview 4 5System features exposed from `PackageManager` are defined and aggregated as 6`<feature>` xml attributes across various partitions, and are currently queried 7at runtime through the framework. This directory contains tooling that supports 8*build-time* queries of select system features, enabling optimizations 9like code stripping and conditionally dependencies when so configured. 10 11### System Feature Codegen 12 13As not all system features can be fully specified or defined at build time (e.g. 14updatable partitisions and apex modules can change/remove such features), we 15use a conditional, build flag approach that allows a given device to customize 16the subset of build-time defined system features that are immutable and cannot 17be updated. 18 19#### Build Flags 20 21System features that can be fixed at build-time are declared in a common 22location, `build/release/flag_declarations/`. These have the form 23`RELEASE_SYSTEM_FEATURE_${X}`, where `${X}` corresponds to a feature defined in 24`PackageManager`, e.g., `TELEVISION` or `WATCH`. 25 26Build flag values can then be defined per device (or form factor), where such 27values either indicate the existence/version of the system feature, or that the 28feature is unavailable, e.g., for TV, we could define these build flag values: 29``` 30name: "RELEASE_SYSTEM_FEATURE_TELEVISION" 31value: { 32 string_value: "0" # Feature version = 0 33} 34``` 35``` 36name: "RELEASE_SYSTEM_FEATURE_WATCH" 37value: { 38 string_value: "UNAVAILABLE" 39} 40``` 41 42See also [SystemFeaturesGenerator](src/com/android/systemfeatures/SystemFeaturesGenerator.kt) 43for more details. 44 45#### Runtime Queries 46 47Each declared build flag system feature is routed into codegen, generating a 48getter API in the internal class, `com.android.internal.pm.RoSystemFeatures`: 49``` 50class RoSystemFeatures { 51 ... 52 public static boolean hasFeatureX(Context context); 53 ... 54} 55``` 56By default, these queries simply fall back to the usual 57`PackageManager.hasSystemFeature(...)` runtime queries. However, if a device 58defines these features via build flags, the generated code will add annotations 59indicating fixed value for this query, and adjust the generated code to return 60the value directly. This in turn enables build-time stripping and optimization. 61 62> **_NOTE:_** Any build-time defined system features will also be implicitly 63used to accelerate calls to `PackageManager.hasSystemFeature(...)` for the 64feature, avoiding binder calls when possible. 65 66#### Lint 67 68A new `ErrorProne` rule is introduced to assist with migration and maintenance 69of codegen APIs for build-time defined system features. This is defined in the 70`systemfeatures-errorprone` build rule, which can be added to any Java target's 71`plugins` list. 72 73// TODO(b/203143243): Add plugin to key system targets after initial migration. 74 751) Add the plugin dependency to a given `${TARGET}`: 76``` 77java_library { 78 name: "${TARGET}", 79 plugins: ["systemfeatures-errorprone"], 80} 81``` 822) Run locally: 83``` 84RUN_ERROR_PRONE=true m ${TARGET} 85``` 863) (Optional) Update the target rule to generate in-place patch files: 87``` 88java_library { 89 name: "${TARGET}", 90 plugins: ["systemfeatures-errorprone"], 91 // DO NOT SUBMIT: GENERATE IN-PLACE PATCH FILES 92 errorprone: { 93 javacflags: [ 94 "-XepPatchChecks:RoSystemFeaturesChecker", 95 "-XepPatchLocation:IN_PLACE", 96 ], 97 } 98 ... 99} 100``` 101``` 102RUN_ERROR_PRONE=true m ${TARGET} 103``` 104 105See also [RoSystemFeaturesChecker](errorprone/java/com/android/systemfeatures/errorprone/RoSystemFeaturesChecker.java) 106for more details. 107 108> **_NOTE:_** Not all system feature queries or targets need or should be 109migrated. Only system features that are explicitly declared with build flags, 110and only targets that are built with the platform (i.e., not updatable), are 111candidates for this linting and migration, e.g., SystemUI, System Server, etc... 112 113// TODO(b/203143243): Wrap the in-place lint updates with a simple script for convenience. 114