Merge "Document resources staging groups and finalization" into tm-dev am: 1b4cf0ce

  <public type="id" name="accessibilityActionDragDrop" id="0x01020056" />

  <public type="id" name="accessibilityActionDragCancel" id="0x01020057" />

  <!-- ===============================================================

    Resources added in version T of the platform

    NOTE: add <public> elements within a <staging-public-group> like so:

    <staging-public-group type="attr" first-id="0x01ff0000">

        <public name="exampleAttr1" />

        <public name="exampleAttr2" />

    </staging-public-group>

    To add a new <staging-public-group> block, find the id value for the

    last <staging-public-group> block defined for thie API level, and

    subtract 0x00010000 from it to get to the id of the new block.

    For example, if the block closest to the end of this file has an id

    of 0x01ee0000, the id of the new block should be 0x01ed0000

    (0x01ee0000 - 0x00010000 = 0x01ed0000).

    =============================================================== -->

  <eat-comment />

  <staging-public-group type="attr" first-id="0x01df0000">

    <public name="sharedUserMaxSdkVersion" />

    <public name="requiredSplitTypes" />

    <public name="splitTypes" />

    <public name="canDisplayOnRemoteDevices" />

    <public name="supportedTypes" />

    <public name="resetEnabledSettingsOnAppDataCleared" />

    <public name="supportsStylusHandwriting" />

    <public name="showClockAndComplications" />

    <!-- @hide @SystemApi -->

    <public name="gameSessionService" />

    <public name="supportsBatteryGameMode" />

    <public name="supportsPerformanceGameMode" />

    <public name="allowGameAngleDriver" />

    <public name="allowGameDownscaling" />

    <public name="allowGameFpsOverride" />

    <public name="localeConfig" />

    <public name="showBackground" />

    <public name="useTargetActivityForQuickAccess"/>

    <public name="inheritKeyStoreKeys" />

    <public name="preferKeepClear" />

    <public name="autoHandwritingEnabled" />

    <public name="fromExtendLeft" />

    <public name="fromExtendTop" />

    <public name="fromExtendRight" />

    <public name="fromExtendBottom" />

    <public name="toExtendLeft" />

    <public name="toExtendTop" />

    <public name="toExtendRight" />

    <public name="toExtendBottom" />

    <public name="tileService" />

    <public name="windowSplashScreenBehavior" />

    <public name="allowUntrustedActivityEmbedding" />

    <public name="knownActivityEmbeddingCerts" />

    <public name="intro" />

    <public name="enableOnBackInvokedCallback" />

    <public name="supportsInlineSuggestionsWithTouchExploration" />

    <public name="lineBreakStyle" />

    <public name="lineBreakWordStyle" />

  </staging-public-group>

  <staging-public-group type="id" first-id="0x01de0000">

    <public name="removed_accessibilityActionSwipeLeft" />

    <public name="removed_accessibilityActionSwipeRight" />

    <public name="removed_accessibilityActionSwipeUp" />

    <public name="removed_accessibilityActionSwipeDown" />

    <public name="accessibilityActionShowTextSuggestions" />

    <public name="inputExtractAction" />

    <public name="inputExtractAccessories" />

  </staging-public-group>

  <staging-public-group type="style" first-id="0x01dd0000">

    <public name="TextAppearance.DeviceDefault.Headline" />

  </staging-public-group>

  <staging-public-group type="string" first-id="0x01dc0000">

    <!-- @hide @SystemApi -->

    <public name="config_systemSupervision" />

    <!-- @hide @SystemApi -->

    <public name="config_devicePolicyManagement" />

    <!-- @hide @SystemApi -->

    <public name="config_systemAppProtectionService" />

    <!-- @hide @SystemApi @TestApi -->

    <public name="config_systemAutomotiveCalendarSyncManager" />

    <!-- @hide @SystemApi -->

    <public name="config_defaultAutomotiveNavigation" />

  </staging-public-group>

  <staging-public-group type="dimen" first-id="0x01db0000">

  </staging-public-group>

  <staging-public-group type="color" first-id="0x01da0000">

  </staging-public-group>

  <staging-public-group type="array" first-id="0x01d90000">

    <!-- @hide @SystemApi -->

    <public name="config_optionalIpSecAlgorithms" />

  </staging-public-group>

  <staging-public-group type="drawable" first-id="0x01d80000">

  </staging-public-group>

  <staging-public-group type="layout" first-id="0x01d70000">

  </staging-public-group>

  <staging-public-group type="anim" first-id="0x01d60000">

  </staging-public-group>

  <staging-public-group type="animator" first-id="0x01d50000">

  </staging-public-group>

  <staging-public-group type="interpolator" first-id="0x01d40000">

  </staging-public-group>

  <staging-public-group type="mipmap" first-id="0x01d30000">

  </staging-public-group>

  <staging-public-group type="integer" first-id="0x01d20000">

  </staging-public-group>

  <staging-public-group type="transition" first-id="0x01d10000">

  </staging-public-group>

  <staging-public-group type="raw" first-id="0x01d00000">

  </staging-public-group>

  <staging-public-group type="bool" first-id="0x01cf0000">

    <!-- @hide @TestApi -->

    <public name="config_preventImeStartupUnlessTextEditor" />

    <!-- @hide @SystemApi -->

    <public name="config_enableQrCodeScannerOnLockScreen" />

  </staging-public-group>

  <staging-public-group type="fraction" first-id="0x01ce0000">

  </staging-public-group>

  <!-- ===============================================================

       DO NOT ADD UN-GROUPED ITEMS HERE

       Any new items (attrs, styles, ids, etc.) *must* be added in a

       staging-public-group block, as the preceding comment explains.

       Items added outside of a group may have their value recalculated

       every time something new is added to this file.

       =============================================================== -->

</resources>

<?xml version="1.0" encoding="utf-8"?>

<!--

    Exposing a new resource:

        To add a new entry, find the corresponding "staging-public-group" with the correct type for

        your resource, and add a new entry to the BOTTOM of the list. This ensures that indexes

        don't shift for previously added resources, and the new one will be appended to the end.

        To add R.attr.exampleAttrName:

            <staging-public-group type="attr" first-id="0x1ff0000">

                <public name="previouslyAdded1"/>

                <public name="previouslyAdded2"/>

                <public name="exampleAttrName"/>

            </staging-public-group>

    Deleting a resource:

        If a resource is no longer supported/used, it can be marked removed by renaming the

        resource with a `removed_` prefix. This preserves the indexes of other resources so as not

        to break apps that have compiled with their integers previously.

        To remove R.attr.previouslyAdded2:

            <staging-public-group type="attr" first-id="0x1ff0000">

                <public name="previouslyAdded1"/>

                <public name="removed_previouslyAdded2"/>

                <public name="exampleAttrName"/>

            </staging-public-group>

        IMPORTANT: Deleting an entry is never allowed, even across branches or reverts. Please take

        this into account before merging a change which edits this file. Small, isolated changes

        which only add/remove resources is recommended to avoid reverts due to build/test failures.

    Renaming a resource:

        This is generally fine and can be done to the entry directly, with no other changes. But

        note that any apps/tooling that resolve against resource names rather than IDs may break

        as a result. This is uncommon, but not rare.

    Finalizing a release's resources:

        1. $ANDROID_BUILD_TOP/frameworks/base/tools/aapt2/tools/finalize_res.py \

           $ANDROID_BUILD_TOP/frameworks/base/core/res/res/values/public-staging.xml \

           $ANDROID_BUILD_TOP/frameworks/base/core/res/res/values/public-final.xml

        2. Rename "NEXT" in the new public-staging.xml resources header to the next platform short

           version code

    Finalizing a release's resources (manually; only for reference):

        1. Delete all "staging-public-group" blocks for the release with no entries inside them

        2. Rename the remaining "staging-public-group" blocks for that release to

           "staging-public-group-final"

        3. Cut them out this file and place at the bottom of public-final.xml; also move the

           "Resources added in version ? of the platform" header

        4. Copy-paste all of the non-"removed_" resources outside of the staging blocks into being

           siblings alongside them

        5. Assign them final public IDs in the form of

           <public type="attr" name="exampleAttrName" id="0x0101088a" />

           by finding the last ID for that type and incrementing the last 4 characters by 1 in

           hexadecimal

        6. Back in this file, seed the next release's resources by adding "staging-public-group"

           tags with their "first-id" value shifted by -0x00010000 from the lowest "first-id"

           in the last used "staging-public-group-final"

        Example:

            Starting public-staging.xml:

                <!\- ===============================================================

                    Resources added in version ? of the platform

                    =============================================================== -\>

                <eat-comment />

                <staging-public-group type="attr" first-id="0x01ff0000">

                    <public name="exampleAttr1"/>

                    <public name="removed_exampleAttr2"/>

                    <public name="exampleAttr3"/>

                </staging-public-group>

                <staging-public-group type="id" first-id="0x01fe0000">

                </staging-public-group>

            Resulting public-final.xml:

                <!\- ===============================================================

                    Resources added in version ? of the platform

                    =============================================================== -\>

                <eat-comment />

                <staging-public-group-final type="attr" first-id="0x01ff0000">

                    <public name="exampleAttr1"/>

                    <public name="removed_exampleAttr2"/>

                    <public name="exampleAttr3"/>

                </staging-public-group-final>

                <public type="id" name="exampleAttr1" id="0x0101088a"/>

                <public type="id" name="exampleAttr3" id="0x0101088b"/>

            Resulting public-staging.xml:

                <!\- ===============================================================

                    Resources added in version (? + 1) of the platform

                    =============================================================== -\>

                <eat-comment />

                <staging-public-group type="attr" first-id="0x01fd0000">

                </staging-public-group>

                <staging-public-group type="id" first-id="0x01fc0000">

                </staging-public-group>

-->

<resources>

  <!-- ===============================================================

    Resources added in version T of the platform

    NOTE: After this version of the platform is forked, changes cannot be made to the root

    branch's groups for that release. Only merge changes to the forked platform branch.

    =============================================================== -->

  <eat-comment/>

  <staging-public-group type="attr" first-id="0x01df0000">

    <public name="sharedUserMaxSdkVersion" />

    <public name="requiredSplitTypes" />

    <public name="splitTypes" />

    <public name="canDisplayOnRemoteDevices" />

    <public name="supportedTypes" />

    <public name="resetEnabledSettingsOnAppDataCleared" />

    <public name="supportsStylusHandwriting" />

    <public name="showClockAndComplications" />

    <!-- @hide @SystemApi -->

    <public name="gameSessionService" />

    <public name="supportsBatteryGameMode" />

    <public name="supportsPerformanceGameMode" />

    <public name="allowGameAngleDriver" />

    <public name="allowGameDownscaling" />

    <public name="allowGameFpsOverride" />

    <public name="localeConfig" />

    <public name="showBackground" />

    <public name="useTargetActivityForQuickAccess"/>

    <public name="inheritKeyStoreKeys" />

    <public name="preferKeepClear" />

    <public name="autoHandwritingEnabled" />

    <public name="fromExtendLeft" />

    <public name="fromExtendTop" />

    <public name="fromExtendRight" />

    <public name="fromExtendBottom" />

    <public name="toExtendLeft" />

    <public name="toExtendTop" />

    <public name="toExtendRight" />

    <public name="toExtendBottom" />

    <public name="tileService" />

    <public name="windowSplashScreenBehavior" />

    <public name="allowUntrustedActivityEmbedding" />

    <public name="knownActivityEmbeddingCerts" />

    <public name="intro" />

    <public name="enableOnBackInvokedCallback" />

    <public name="supportsInlineSuggestionsWithTouchExploration" />

    <public name="lineBreakStyle" />

    <public name="lineBreakWordStyle" />

  </staging-public-group>

  <staging-public-group type="id" first-id="0x01de0000">

    <public name="removed_accessibilityActionSwipeLeft" />

    <public name="removed_accessibilityActionSwipeRight" />

    <public name="removed_accessibilityActionSwipeUp" />

    <public name="removed_accessibilityActionSwipeDown" />

    <public name="accessibilityActionShowTextSuggestions" />

    <public name="inputExtractAction" />

    <public name="inputExtractAccessories" />

  </staging-public-group>

  <staging-public-group type="style" first-id="0x01dd0000">

    <public name="TextAppearance.DeviceDefault.Headline" />

  </staging-public-group>

  <staging-public-group type="string" first-id="0x01dc0000">

    <!-- @hide @SystemApi -->

    <public name="config_systemSupervision" />

    <!-- @hide @SystemApi -->

    <public name="config_devicePolicyManagement" />

    <!-- @hide @SystemApi -->

    <public name="config_systemAppProtectionService" />

    <!-- @hide @SystemApi @TestApi -->

    <public name="config_systemAutomotiveCalendarSyncManager" />

    <!-- @hide @SystemApi -->

    <public name="config_defaultAutomotiveNavigation" />

  </staging-public-group>

  <staging-public-group type="dimen" first-id="0x01db0000">

  </staging-public-group>

  <staging-public-group type="color" first-id="0x01da0000">

  </staging-public-group>

  <staging-public-group type="array" first-id="0x01d90000">

    <!-- @hide @SystemApi -->

    <public name="config_optionalIpSecAlgorithms" />

  </staging-public-group>

  <staging-public-group type="drawable" first-id="0x01d80000">

  </staging-public-group>

  <staging-public-group type="layout" first-id="0x01d70000">

  </staging-public-group>

  <staging-public-group type="anim" first-id="0x01d60000">

  </staging-public-group>

  <staging-public-group type="animator" first-id="0x01d50000">

  </staging-public-group>

  <staging-public-group type="interpolator" first-id="0x01d40000">

  </staging-public-group>

  <staging-public-group type="mipmap" first-id="0x01d30000">

  </staging-public-group>

  <staging-public-group type="integer" first-id="0x01d20000">

  </staging-public-group>

  <staging-public-group type="transition" first-id="0x01d10000">

  </staging-public-group>

  <staging-public-group type="raw" first-id="0x01d00000">

  </staging-public-group>

  <staging-public-group type="bool" first-id="0x01cf0000">

    <!-- @hide @TestApi -->

    <public name="config_preventImeStartupUnlessTextEditor" />

    <!-- @hide @SystemApi -->

    <public name="config_enableQrCodeScannerOnLockScreen" />

  </staging-public-group>

  <staging-public-group type="fraction" first-id="0x01ce0000">

  </staging-public-group>

</resources>

#!/usr/bin/env python3

# -*- coding: utf-8 -*-

#  Copyright (C) 2022 The Android Open Source Project

#

#  Licensed under the Apache License, Version 2.0 (the "License");

#  you may not use this file except in compliance with the License.

#  You may obtain a copy of the License at

#

#       http://www.apache.org/licenses/LICENSE-2.0

#

#  Unless required by applicable law or agreed to in writing, software

#  distributed under the License is distributed on an "AS IS" BASIS,

#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

#  See the License for the specific language governing permissions and

#  limitations under the License.

#

# Licensed under the Apache License, Version 2.0 (the 'License');

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

#      http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an 'AS IS' BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

"""

Finalize resource values in <staging-public-group> tags

and convert those to <staging-public-group-final>

Usage: $ANDROID_BUILD_TOP/frameworks/base/tools/aapt2/tools/finalize_res.py \

           $ANDROID_BUILD_TOP/frameworks/base/core/res/res/values/public-staging.xml \

           $ANDROID_BUILD_TOP/frameworks/base/core/res/res/values/public-final.xml

"""

import re

import sys

resTypes = ["attr", "id", "style", "string", "dimen", "color", "array", "drawable", "layout",

            "anim", "animator", "interpolator", "mipmap", "integer", "transition", "raw", "bool",

            "fraction"]

_type_ids = {}

_type = ""

_lowest_staging_first_id = 0x01FFFFFF

"""

    Created finalized <public> declarations for staging resources, ignoring them if they've been

    prefixed with removed_. The IDs are assigned without holes starting from the last ID for that

    type currently finalized in public-final.xml.

"""

def finalize_item(raw):

    name = raw.group(1)

    if re.match(r'_*removed.+', name):

        return ""

    id = _type_ids[_type]

    _type_ids[_type] += 1

    return '  <public type="%s" name="%s" id="%s" />\n' % (_type, name, '0x{0:0{1}x}'.format(id, 8))

"""

    Finalizes staging-public-groups if they have any entries in them. Also keeps track of the

    lowest first-id of the non-empty groups so that the next release's staging-public-groups can

    be assigned the next down shifted first-id.

"""

def finalize_group(raw):

    global _type, _lowest_staging_first_id

    _type = raw.group(1)

    id = int(raw.group(2), 16)

    _type_ids[_type] = _type_ids.get(_type, id)

    (res, count) = re.subn(' {0,4}<public name="(.+?)" */>\n', finalize_item, raw.group(3))

    if count > 0:

        res = raw.group(0).replace("staging-public-group",

                                   "staging-public-group-final") + '\n' + res

        _lowest_staging_first_id = min(id, _lowest_staging_first_id)

    return res

"""

    Collects the max ID for each resType so that the new IDs can be assigned afterwards

"""

def collect_ids(raw):

    for m in re.finditer(r'<public type="(.+?)" name=".+?" id="(.+?)" />', raw):

        type = m.group(1)

        id = int(m.group(2), 16)

        _type_ids[type] = max(id + 1, _type_ids.get(type, 0))

with open(sys.argv[1], "r+") as stagingFile:

    with open(sys.argv[2], "r+") as finalFile:

        existing = finalFile.read()

        # Cut out the closing resources tag so that it can be concatenated easily later

        existing = "\n".join(existing.rsplit("</resources>", 1))

        # Collect the IDs from the existing already finalized resources

        collect_ids(existing)

        staging = stagingFile.read()

        stagingSplit = staging.rsplit("<resources>")

        staging = stagingSplit[1]

        staging = re.sub(

            r'<staging-public-group type="(.+?)" first-id="(.+?)">(.+?)</staging-public-group>',

            finalize_group, staging, flags=re.DOTALL)

        staging = re.sub(r' *\n', '\n', staging)

        staging = re.sub(r'\n{3,}', '\n\n', staging)

        # First write the existing finalized declarations and then append the new stuff

        finalFile.seek(0)

        finalFile.write(existing.strip("\n"))

        finalFile.write("\n\n")

        finalFile.write(staging.strip("\n"))

        finalFile.write("\n")

        finalFile.truncate()

        stagingFile.seek(0)

        # Include the documentation from public-staging.xml that was previously split out

        stagingFile.write(stagingSplit[0])

        # Write the next platform header

        stagingFile.write("<resources>\n\n")

        stagingFile.write("  <!-- ===============================================================\n")

        stagingFile.write("    Resources added in version NEXT of the platform\n\n")

        stagingFile.write("    NOTE: After this version of the platform is forked, changes cannot be made to the root\n")

        stagingFile.write("    branch's groups for that release. Only merge changes to the forked platform branch.\n")

        stagingFile.write("    =============================================================== -->\n")

        stagingFile.write("  <eat-comment/>\n\n")

        # Seed the next release's staging-public-groups as empty declarations,

        # so its easy for another developer to expose a new public resource

        nextId = _lowest_staging_first_id - 0x00010000

        for resType in resTypes:

            stagingFile.write('  <staging-public-group type="%s" first-id="%s">\n'

                              '  </staging-public-group>\n\n' %

                              (resType, '0x{0:0{1}x}'.format(nextId, 8)))

            nextId -= 0x00010000

        # Close the resources tag and truncate, since the file will be shorter than the previous

        stagingFile.write("</resources>\n")

        stagingFile.truncate()

#!/usr/bin/env python3

#-*- coding: utf-8 -*-

# Copyright (C) 2021 The Android Open Source Project

#

# Licensed under the Apache License, Version 2.0 (the 'License');

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

#      http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an 'AS IS' BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

"""

Finalize resource values in <staging-public-group> tags

Usage: finalize_res.py core/res/res/values/public.xml public_finalized.xml

"""

import re, sys, codecs

def finalize_item(raw):

    global _type, _id

    _id += 1

    return '<public type="%s" name="%s" id="%s" />' % (_type, raw.group(1), '0x{0:0{1}x}'.format(_id-1,8))

def finalize_group(raw):

    global _type, _id

    _type = raw.group(1)

    _id = int(raw.group(2), 16)

    return re.sub(r'<public name="(.+?)" */>', finalize_item, raw.group(3))

with open(sys.argv[1]) as f:

    raw = f.read()

    raw = re.sub(r'<staging-public-group type="(.+?)" first-id="(.+?)">(.+?)</staging-public-group>', finalize_group, raw, flags=re.DOTALL)

    with open(sys.argv[2], "w") as f:

        f.write(raw)