rules/apis/java_api_contribution.bzl

"""
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.
"""

"""Bazel rules for exporting API contributions of Java libraries"""

"""A Bazel provider that encapsulates the contributions of a Java library to an API surface"""
JavaApiContributionInfo = provider(
    fields = {
        "name": "Name of the contribution target",
        "api": "Path of partial current.txt file describing the stable APIs of the library. Path is relative to workspace root",
        "api_surfaces": "List of API surfaces that this partial api file contributes to",
    },
)

_PUBLIC_API = "publicapi"
_SYSTEM_API = "systemapi"
_TEST_API = "testapi"
_MODULE_LIB_API = "module-libapi"
_SYSTEM_SERVER_API = "system-serverapi"
_INTRA_CORE_API = "intracoreapi"
_CORE_PLATFORM_API = "core_platformapi"

# _TOOLCHAIN_API is a special API surface provided by ART to compile other API domains
# (e.g. core-lambda-stubs required to compile java files containing lambdas)
# This is not part of go/android-api-types, and is not available to apps at runtime
_TOOLCHAIN_API = "toolchainapi"

# Java API surfaces are hierarchical.
# This hierarchy map was created by looking at the stub definitions in frameworks/base/StubLibraries.bp
# Key is the full api surface
# Values are the partial metalava signature files that are combined to generate the full api surface stubs.
_JAVA_FULLAPISURFACE_TO_PARTIALSIGNATUREFILE = {
    _PUBLIC_API: [_PUBLIC_API],
    _SYSTEM_API: [_PUBLIC_API, _SYSTEM_API],
    _TEST_API: [_PUBLIC_API, _SYSTEM_API, _TEST_API],
    _MODULE_LIB_API: [_PUBLIC_API, _SYSTEM_API, _MODULE_LIB_API],
    _SYSTEM_SERVER_API: [_PUBLIC_API, _SYSTEM_API, _MODULE_LIB_API, _SYSTEM_SERVER_API],
    # intracore is publicapi + "@IntraCoreApi".
    # e.g. art.module.intra.core.api uses the following `droiddoc_option`
    # [<hide>, --show-single-annotation libcore.api.IntraCoreApi"]
    # conscrypt and icu4j use similar droidoc_options
    _INTRA_CORE_API: [_PUBLIC_API, _INTRA_CORE_API],
    # CorePlatformApi does not extend PublicApi
    # Each core module is at different stages of transition
    # The status quo in Soong today is
    # 1. conscrypt - Still provides CorePlatformApis
    # 2. i18n - APIs have migrated to Public API surface
    # 3. art - APIs have migrated to ModuleLib API suface
    # This layering complexity will be handled by the build orchestrator and not by API export.
    _CORE_PLATFORM_API: [_CORE_PLATFORM_API],
    # coreapi does not have an entry here, it really is the public stubs of the 3 core modules
    # (art, conscrypt, i18n)
    _TOOLCHAIN_API: [_TOOLCHAIN_API],
}

VALID_JAVA_API_SURFACES = _JAVA_FULLAPISURFACE_TO_PARTIALSIGNATUREFILE.keys()

def _java_api_contribution_impl(ctx):
    """Implemenation for the java_api_contribution rule
    This rule does not have any build actions, but returns a `JavaApiContributionInfo` provider object"""

    full_api_surfaces = []

    # The checked-in signature files are parital signatures. e.g. SystemAPI surface
    # (android_system_stubs_current.jar) contains the classes
    # and methods present in current.txt and system-current.txt.
    # The jar representing the full api surface is created by combining these partial signature files.
    for full_api_surface, partials in _JAVA_FULLAPISURFACE_TO_PARTIALSIGNATUREFILE.items():
        if ctx.attr.api_surface in partials:
            full_api_surfaces.append(full_api_surface)

    return [
        JavaApiContributionInfo(
            name = ctx.label.name,
            api = ctx.file.api.path,
            api_surfaces = full_api_surfaces,
        ),
    ]

java_api_contribution = rule(
    implementation = _java_api_contribution_impl,
    attrs = {
        "api": attr.label(
            mandatory = True,
            allow_single_file = [".txt"],
            doc = "The partial signature file describing the APIs of this module",
        ),
        # TODO: Better name for this
        "api_surface": attr.string(
            doc = "The partial api surface signature represented by this file. See _JAVA_FULLAPISURFACE_TO_PARTIALSIGNATUREFILE in java_api_contribution.bzl for relationship between partial signature files and full API surfaces",
            default = "publicapi",
            values = VALID_JAVA_API_SURFACES,
        ),
    },
)