README.md
1# SdkExtensions module
2
3SdkExtensions module is responsible for:
4- deciding the extension SDK level of the device;
5- providing APIs for applications to query the extension SDK level;
6- determining the values for the BOOTCLASSPATH, DEX2OATBOOTCLASSPATH, and
7 SYSTEMSERVERCLASSPATH environment variables.
8
9## General information
10
11### Structure
12
13The module is packaged in an apex, `com.android.sdkext`, and has several
14components:
15- `bin/derive_classpath`: a native binary that runs early in the device boot
16 process. It reads individual classpath configs files from the system and
17 other modules, merges them, and defines the definition of *CLASSPATH environ
18 variables.
19- `bin/derive_sdk`: native binary that runs early in the device boot process and
20 reads metadata of other modules, to set system properties relating to the
21 extension SDK (for instance `build.version.extensions.r`).
22- `javalib/framework-sdkextension.jar`: this is a jar on the bootclasspath that
23 exposes APIs to applications to query the extension SDK level.
24
25### Deriving extension SDK level
26`derive_sdk` is a program that reads metadata stored in other apex modules, in
27the form of binary protobuf files in subpath `etc/sdkinfo.pb` inside each
28apex. The structure of this protobuf can be seen [here][sdkinfo-proto]. The
29exact steps for converting a set of metadata files to actual extension versions
30is likely to change over time, and should not be depended upon.
31
32### Reading extension SDK level
33The module exposes a java class [`SdkExtensions`][sdkextensions-java] in the
34package `android.os.ext`. The method `getExtensionVersion(int)` can be used to
35read the version of a particular sdk extension, e.g.
36`getExtensionVersion(Build.VERSION_CODES.R)`.
37
38### Deriving classpaths
39`derive_classpath` service reads and merges individual config files in the
40`/system/etc/classpaths/` and `/apex/*/etc/classpaths`. Each config stores
41protobuf message from [`classpaths.proto`] in a proto binary format. Exact
42merging algorithm that determines the order of the classpath entries is
43described in [`derive_classpath.cpp`] and may change over time.
44
45[`classpaths.proto`]: packages/modules/SdkExtensions/proto/classpaths.proto
46[`derive_classpath.cpp`]: packages/modules/SdkExtensions/derive_classpath/derive_classpath.cpp
47[sdkinfo-proto]: packages/modules/SdkExtensions/proto/sdk.proto
48[sdkextensions-java]: framework/java/android/os/ext/SdkExtensions.java
49
50## Developer information
51
52### Adding a new extension version
53For every new Android SDK level a new extension version should be defined. These
54are the steps necessary to do that:
55- Add the new modules in this extension version to the SdkModule enum in
56 sdk.proto.
57- Update `derive_sdk.cpp` by:
58 * mapping the modules' package names to the new enum values
59 * creating a new set with the new enum values
60 * set a new sysprop to the value of `GetSdkLevel` with the new enum set
61 * add a unit test to `derive_sdk_test.cpp` verifying the new extensions works
62- Make the `SdkExtensions.getExtensionVersion` API support the new extensions.
63- Extend the CTS test to verify the above two behaviors.
64- Update `RollbackManagerServiceImpl#getExtensionVersions` to account for the
65 new extension version.
66