A devices.xml profile's device type, API range, Play Store and screen size decide its class and images

Start with src/drivers/android/device-profile-source.ts and its tests to see how devices.xml profiles are parsed, then trace how DeviceProfileRegistry merges them and how src/drivers/android/image-fit.ts applies the profile rules. Run the named parser and Android driver tests, then check the catalog pairing for a profile with API range 31- against images at API 30 and 31. Done means only API 31 is paired and docs/CLI.md describes the profile settings.

Part of #485.

Scope

A profile made in Android Studio's device manager is fitted to images by everything Android Studio saved for it: its API range, its Play Store setting and its screen size, besides the device type #489 already uses. After this PR a custom profile that needs API 31 or newer is never created on API 30, as in Android Studio.

In short

Android Studio saves a custom profile in ~/.android/devices.xml. avdmanager list device reads that file too and lists the profile with OEM : User, but prints only its name, id and device type (Tag :). Simlock now reads the rest from devices.xml itself and adds it to that entry by name. The device is still created by avdmanager -d <id>, as today.

flowchart LR
  A[avdmanager list device:<br/>My TV, OEM User, Tag android-tv] --> M[custom profile]:::changed
  X[devices.xml: My TV<br/>api-level 31-, playstore-enabled, diagonal] --> M
  M --> F[fits rule]
  classDef changed stroke-width:3px

Custom profile in devices.xml	Images after #489	Images after this PR
"My TV", type TV, api-level 31-	TV images, any level	TV images, 31 and newer
"My Phone", no type, api-level 33-	phone images, any level	phone images, 33 and newer
"My Phone", playstore-enabled false	phone images	phone images, no Play Store image
"My Watch", type Wear, playstore-enabled false	Wear images	Wear images, Play Store too (every Wear profile allows it)
"My Tablet", no type, 10.1-inch screen	phone images, no tablet image	phone images and tablet images
"My Phone", no type, no diagonal	phone images, no tablet image	phone images, no tablet image
"My Phone", api-level -	any level	any level
"Old", nothing but a name	phone images	phone images

Classes of custom profiles avdmanager lists do not change: they still come from the device type it prints. A devices.xml profile avdmanager does not list (rare: a different .android directory) gets its class from its tag-id by the same map, phone without one (ADR 0025 §5).

If this goes wrong, a custom profile loses images it used to get, or gets ones Android Studio would not offer.

Technical spec

Modules touched

flowchart LR
  U[parseDevicesXml / UserDeviceProfileSource<br/>device-profile-source.ts]:::changed --> R[DeviceProfileRegistry]:::changed
  B[BuiltinDeviceProfileSource] --> R
  F[image-fit.ts fits]:::changed --> R
  D[AndroidDriver listCatalog, resolveSpec] --> F
  classDef changed stroke-width:3px

• src/drivers/android/device-profile-source.ts:
  • parseDevicesXml also reads, per <d:device>:
    • <d:tag-id>: 1 to 64 characters of a-z, 0-9, -; anything else is ignored.
    • the first <d:software><d:api-level>: - or empty is no range; N- is N and newer; N-M is N to M; -M is M and older; N is exactly N. N and M are integers from 1 to 999, and N ≤ M. Anything else is ignored (no range).
    • <d:playstore-enabled>: true or false; anything else is ignored (allowed).
    • the first <d:screen><d:diagonal-length>: a decimal from 0.1 to 100 (inches); anything else is ignored (not a tablet).
    • foldable: the first <d:screen> has <d:x-folded-dimension> and <d:y-folded-dimension> both above 0, as sdklib's Screen.isFoldable().
  • The properties profile gains imageKind (from tag-id), apiRange, playStore and tablet. tablet is true when the profile has no tag-id, a diagonal of 7 or more, and does not fold, as sdklib's Device.isTablet(). A profile with tag-id android-wear always allows Play Store, as sdklib does.
  • The CR/LF/NUL refusal applies to every new field first, through the parser's existing unreadable-file diagnostic: a line break or NUL inside a value rejects the file even where the value would otherwise be ignored.
  • DeviceProfileRegistry gives a builtin profile marked custom the apiRange, playStore and tablet of the devices.xml profile with the same name, ignoring case, when there is one, on both paths: resolve and catalog. Its kind and class stay from its Tag : line. Which profile a name resolves to, the order and the catalog's model list do not change. So resolve now also reads the devices.xml source after a custom builtin match (a file read; an unreadable file reports its diagnostic and adds nothing); for a model that is not custom it still stops at the first source, as today.
  • The devices.xml path follows the same order avdmanager uses to find .android, read from the environment the driver passes to avdmanager: $ANDROID_USER_HOME/devices.xml, else $ANDROID_PREFS_ROOT/.android/devices.xml, else $ANDROID_SDK_HOME/.android/devices.xml, else <home>/.android/devices.xml. Today it reads only ANDROID_SDK_HOME and home, so both sources now read the same file.
  • DeviceProfileRegistry.catalog classes a properties profile by its imageKind through classOfTag; with none it is phone, as today.
• src/drivers/android/image-fit.ts: fits reads apiRange, playStore and tablet for a custom builtin profile and for a properties profile; a properties profile's kind is its imageKind, none when it has no tag-id.

Contract and event changes

None.

Other code on the same state

• BuiltinDeviceProfileSource: lists every devices.xml profile with OEM : User (avdmanager reads the file itself); it comes before UserDeviceProfileSource, so a custom name resolves to that entry, as today. The merge above adds details to that entry; it does not change which entry wins.
• The existing test "does not read a later source once an earlier one resolves the model" (device-profile-source.test.ts) still holds for a model that is not custom; for a custom one it changes to expect the devices.xml read.
• UserDeviceProfileSource: its properties profiles still answer for a devices.xml profile avdmanager does not list, and are created with #applyHardwareProperties as today. The new fields are not written to config.ini.
• #341 (open): a model's class comes from the profile it was listed from. Not touched here; classes do not change.
• customModels: still lists these profiles as custom.

Rules in play

• safety.md: devices.xml is read only, and its values are claims; every new field is bounded as above and checked for line breaks before use.
• architecture.md: the registry stays the only place that matches names; the merge goes through matchProfile.

Tests

Seam: parseDevicesXml and UserDeviceProfileSource in src/drivers/android/device-profile-source.test.ts; AndroidDriver listCatalog and resolveSpec through createDriver in src/drivers/android/index.test.ts (model on "device-profile sources", which writes devices.xml with writeDevicesXml), with the fake avdmanager list device printing the profile with OEM : User, as a real SDK does.

• reads tag-id, api-level, playstore-enabled, the diagonal and the fold from a devices.xml profile
• parses -, empty, 33-, 24-33, -30 and 33 as the ranges above, and 40-30, abc, 0- and 1000- as no range
• ignores a tag-id outside the allowed characters or length, a diagonal outside 0.1 to 100, and a playstore-enabled other than true/false
• a CR, LF or NUL inside a new field rejects the file through the unreadable-file diagnostic, even when the field's value would otherwise be ignored
• a profile with a tag-id and a 10-inch screen is not a tablet
• reads devices.xml from ANDROID_USER_HOME, then ANDROID_PREFS_ROOT, then ANDROID_SDK_HOME, then home
• a custom profile listed by avdmanager gets the API range of its devices.xml entry: api-level 31- drops levels below 31 from its modelRuntimes
• a custom profile with playstore-enabled false drops Play Store images; a custom Wear profile with false keeps an image tagged android-wear,google_apis_playstore, listed by avdmanager or devices.xml-only
• resolveSpec with --os 30 and provision refuse a custom profile whose api-level is 31-
• a custom profile with no type and a 10.1-inch screen that does not fold fits tablet images; a 6-inch one, one with folded dimensions and one with no diagonal do not
• a custom profile with nothing but a name pairs as after #489
• a custom profile's class still comes from avdmanager's Tag : line
• a devices.xml profile avdmanager does not list fits by its own tag-id, range, Play Store flag and screen, and is classed by its tag-id
• config.ini for a devices.xml profile holds the same keys as before this PR

Done when

• With a custom devices.xml profile whose api-level is 31-, and images at 30 and 31, simlock catalog --platform android --json pairs it only with 31.
• docs/CLI.md ("Where Android models come from") says a custom profile's API range, Play Store setting and screen size from Android Studio decide which images it gets.

Out of scope

• #341.
• Changing a custom profile's class.
• Writing any of these values to config.ini.
• doctor reporting a devices.xml profile hidden by a library name (#491).

Depends on

• #489

Approval

• Approved for delivery

Written by an agent.