• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright (C) 2022 The Android Open Source Project
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""Bazel rules for exporting API contributions of Java libraries"""
16
17load(":api_surface.bzl", "CORE_PLATFORM_API", "INTRA_CORE_API", "MODULE_LIB_API", "PUBLIC_API", "SYSTEM_API", "SYSTEM_SERVER_API", "TEST_API", "TOOLCHAIN_API")
18
19"""A Bazel provider that encapsulates the contributions of a Java library to an API surface"""
20JavaApiContributionInfo = provider(
21    fields = {
22        "name": "Name of the contribution target",
23        "api": "Path of partial current.txt file describing the stable APIs of the library. Path is relative to workspace root",
24        "api_surfaces": "List of API surfaces that this partial api file contributes to",
25    },
26)
27
28# Java API surfaces are hierarchical.
29# This hierarchy map was created by looking at the stub definitions in frameworks/base/StubLibraries.bp
30# Key is the full api surface
31# Values are the partial metalava signature files that are combined to generate the full api surface stubs.
32_JAVA_FULLAPISURFACE_TO_PARTIALSIGNATUREFILE = {
33    PUBLIC_API: [PUBLIC_API],
34    SYSTEM_API: [PUBLIC_API, SYSTEM_API],
35    TEST_API: [PUBLIC_API, SYSTEM_API, TEST_API],
36    MODULE_LIB_API: [PUBLIC_API, SYSTEM_API, MODULE_LIB_API],
37    SYSTEM_SERVER_API: [PUBLIC_API, SYSTEM_API, MODULE_LIB_API, SYSTEM_SERVER_API],
38    # intracore is publicapi + "@IntraCoreApi".
39    # e.g. art.module.intra.core.api uses the following `droiddoc_option`
40    # [<hide>, --show-single-annotation libcore.api.IntraCoreApi"]
41    # conscrypt and icu4j use similar droidoc_options
42    INTRA_CORE_API: [PUBLIC_API, INTRA_CORE_API],
43    # CorePlatformApi does not extend PublicApi
44    # Each core module is at different stages of transition
45    # The status quo in Soong today is
46    # 1. conscrypt - Still provides CorePlatformApis
47    # 2. i18n - APIs have migrated to Public API surface
48    # 3. art - APIs have migrated to ModuleLib API suface
49    # This layering complexity will be handled by the build orchestrator and not by API export.
50    CORE_PLATFORM_API: [CORE_PLATFORM_API],
51    # coreapi does not have an entry here, it really is the public stubs of the 3 core modules
52    # (art, conscrypt, i18n)
53    TOOLCHAIN_API: [TOOLCHAIN_API],
54}
55
56VALID_JAVA_API_SURFACES = _JAVA_FULLAPISURFACE_TO_PARTIALSIGNATUREFILE.keys()
57
58def _java_api_contribution_impl(ctx):
59    """Implemenation for the java_api_contribution rule
60    This rule does not have any build actions, but returns a `JavaApiContributionInfo` provider object"""
61
62    full_api_surfaces = []
63
64    # The checked-in signature files are parital signatures. e.g. SystemAPI surface
65    # (android_system_stubs_current.jar) contains the classes
66    # and methods present in current.txt and system-current.txt.
67    # The jar representing the full api surface is created by combining these partial signature files.
68    for full_api_surface, partials in _JAVA_FULLAPISURFACE_TO_PARTIALSIGNATUREFILE.items():
69        if ctx.attr.api_surface in partials:
70            full_api_surfaces.append(full_api_surface)
71
72    return [
73        JavaApiContributionInfo(
74            name = ctx.label.name,
75            api = ctx.file.api.path,
76            api_surfaces = full_api_surfaces,
77        ),
78    ]
79
80java_api_contribution = rule(
81    implementation = _java_api_contribution_impl,
82    attrs = {
83        "api": attr.label(
84            mandatory = True,
85            allow_single_file = [".txt"],
86            doc = "The partial signature file describing the APIs of this module",
87        ),
88        # TODO: Better name for this
89        "api_surface": attr.string(
90            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",
91            default = "publicapi",
92            values = VALID_JAVA_API_SURFACES,
93        ),
94    },
95)
96