70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# SdkExtensions module
|
|
|
|
SdkExtensions module is responsible for:
|
|
- deciding the extension SDK level of the device;
|
|
- providing APIs for applications to query the extension SDK level;
|
|
- determining the values for the BOOTCLASSPATH, DEX2OATBOOTCLASSPATH, and
|
|
SYSTEMSERVERCLASSPATH environment variables.
|
|
|
|
## General information
|
|
|
|
### Structure
|
|
|
|
The module is packaged in an apex, `com.android.sdkext`, and has several
|
|
components:
|
|
- `bin/derive_classpath`: a native binary that runs early in the device boot
|
|
process. It reads individual classpath configs files from the system and
|
|
other modules, merges them, and defines the definition of *CLASSPATH environ
|
|
variables.
|
|
- `bin/derive_sdk`: native binary that runs early in the device boot process and
|
|
reads metadata of other modules, to set system properties relating to the
|
|
extension SDK (for instance `build.version.extensions.r`).
|
|
- `javalib/framework-sdkextension.jar`: this is a jar on the bootclasspath that
|
|
exposes APIs to applications to query the extension SDK level.
|
|
|
|
### Deriving extension SDK level
|
|
`derive_sdk` is a program that reads metadata stored in other apex modules, in
|
|
the form of binary protobuf files in subpath `etc/sdkinfo.pb` inside each
|
|
apex. The structure of this protobuf can be seen [here][sdkinfo-proto]. The
|
|
exact steps for converting a set of metadata files to actual extension versions
|
|
is likely to change over time, and should not be depended upon.
|
|
|
|
### Reading extension SDK level
|
|
The module exposes a java class [`SdkExtensions`][sdkextensions-java] in the
|
|
package `android.os.ext`. The method `getExtensionVersion(int)` can be used to
|
|
read the version of a particular sdk extension, e.g.
|
|
`getExtensionVersion(Build.VERSION_CODES.R)`.
|
|
|
|
### Deriving classpaths
|
|
`derive_classpath` service reads and merges individual config files in the
|
|
`/system/etc/classpaths/` and `/apex/*/etc/classpaths`. Each config stores
|
|
protobuf message from [`classpaths.proto`] in a proto binary format. Exact
|
|
merging algorithm that determines the order of the classpath entries is
|
|
described in [`derive_classpath.cpp`] and may change over time.
|
|
|
|
[`classpaths.proto`]: packages/modules/SdkExtensions/proto/classpaths.proto
|
|
[`derive_classpath.cpp`]: packages/modules/SdkExtensions/derive_classpath/derive_classpath.cpp
|
|
[sdkinfo-proto]: packages/modules/SdkExtensions/proto/sdk.proto
|
|
[sdkextensions-java]: framework/java/android/os/ext/SdkExtensions.java
|
|
|
|
## Developer information
|
|
|
|
### Adding a new extension
|
|
An extension is a way to group a set of modules so that they are versioned
|
|
together. We currently define a new extension for every Android SDK level
|
|
that introduces new modules. Every module shipped in previous versions are
|
|
also part of the new extension. For example, all the R modules are part of
|
|
both the R extensions and the S extensions.
|
|
|
|
The steps to define a new extension are:
|
|
- Add any new modules to the SdkModule enum in sdk.proto.
|
|
- Add the binary "current sdk version" proto to the apexes of the new modules.
|
|
- Update `derive_sdk.cpp` by:
|
|
* mapping the modules' package names to the new enum values
|
|
* creating a new set with the new enum values of the modules relevant for
|
|
this extension.
|
|
* set a new sysprop to the value of `GetSdkLevel` with the new enum set
|
|
* add a unit test to `derive_sdk_test.cpp` verifying the new extensions work
|
|
- Make the `SdkExtensions.getExtensionVersion` API support the new extensions.
|
|
- Extend the CTS test to verify the above two behaviors.
|