1// Copyright (C) 2019 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// How stubs are generated:
16//
17// raw source files --(metalava)--> stub source files --(javac)--> stub jar files
18//
19// The metalava conversion is done by droidstub modules *-api-stubs-docs.
20// The javac compilation is done by java_library modules android_*_stubs_current.
21// The metalava conversion is also responsible for creating API signature files
22// and comparing them against the last API signature in api/*-current.txt files
23// and also against the latest frozen API signature in prebuilts/sdk/*/*/api/android.txt
24// files.
25
26/////////////////////////////////////////////////////////////////////
27// Common metalava configs
28/////////////////////////////////////////////////////////////////////
29
30packages_to_document = [
31    "android",
32    "dalvik",
33    "java",
34    "javax",
35    "junit",
36    "org.apache.http",
37    "org.json",
38    "org.w3c.dom",
39    "org.xml.sax",
40    "org.xmlpull",
41]
42
43stubs_defaults {
44    name: "metalava-base-api-stubs-default",
45    srcs: [
46        ":framework-non-updatable-sources",
47        "core/java/**/*.logtags",
48        ":opt-telephony-srcs",
49        ":opt-net-voip-srcs",
50        ":art-module-public-api-stubs-source",
51        ":android_icu4j_public_api_files",
52    ],
53    // TODO(b/147699819): remove below aidl includes.
54    aidl: {
55        local_include_dirs: ["telephony/java"],
56    },
57    libs: ["framework-internal-utils"],
58    installable: false,
59    annotations_enabled: true,
60    previous_api: ":android.api.public.latest",
61    merge_annotations_dirs: [
62        "metalava-manual",
63    ],
64    api_levels_annotations_enabled: false,
65    filter_packages: packages_to_document,
66}
67
68stubs_defaults {
69    name: "metalava-full-api-stubs-default",
70    defaults: ["metalava-base-api-stubs-default"],
71    srcs: [
72        ":conscrypt.module.public.api{.public.stubs.source}",
73        ":framework-updatable-sources",
74    ],
75    sdk_version: "core_platform",
76}
77
78stubs_defaults {
79    name: "metalava-non-updatable-api-stubs-default",
80    defaults: ["metalava-base-api-stubs-default"],
81    sdk_version: "core_platform",
82    // There are a few classes from modules used as type arguments that
83    // need to be resolved by metalava. For now, we can use a previously
84    // finalized stub library to resolve them. If a new class gets added,
85    // this may be need to be revisited to use a manually maintained stub
86    // library with empty classes in order to resolve those references.
87    libs: ["sdk_system_30_android"],
88    aidl: {
89        local_include_dirs: ["apex/media/aidl/stable"],
90    },
91}
92
93/////////////////////////////////////////////////////////////////////
94// *-api-stubs-docs modules providing source files for the stub libraries
95/////////////////////////////////////////////////////////////////////
96
97// api-stubs-docs, system-api-stubs-docs, and test-api-stubs-docs have APIs
98// from the non-updatable part of the platform as well as from the updatable
99// modules
100droidstubs {
101    name: "api-stubs-docs",
102    defaults: ["metalava-full-api-stubs-default"],
103    removed_dex_api_filename: "removed-dex.txt",
104    arg_files: [
105        "core/res/AndroidManifest.xml",
106    ],
107    args: metalava_framework_docs_args,
108    check_api: {
109        current: {
110            api_file: "api/current.txt",
111            removed_api_file: "api/removed.txt",
112        },
113        last_released: {
114            api_file: ":android.api.public.latest",
115            removed_api_file: ":removed.api.public.latest",
116            baseline_file: ":public-api-incompatibilities-with-last-released",
117        },
118        api_lint: {
119            enabled: true,
120            new_since: ":android.api.public.latest",
121            baseline_file: "api/lint-baseline.txt",
122        },
123    },
124    dist: {
125        targets: ["sdk", "win_sdk"],
126        dir: "apistubs/android/public/api",
127        dest: "android.txt",
128    },
129    jdiff_enabled: true,
130}
131
132droidstubs {
133    name: "api-stubs-docs-non-updatable",
134    defaults: ["metalava-non-updatable-api-stubs-default"],
135    arg_files: ["core/res/AndroidManifest.xml"],
136    args: metalava_framework_docs_args,
137    check_api: {
138        current: {
139            api_file: "non-updatable-api/current.txt",
140            removed_api_file: "non-updatable-api/removed.txt",
141        },
142        api_lint: {
143            enabled: true,
144            new_since: ":android-non-updatable.api.public.latest",
145        },
146    },
147}
148
149priv_apps = " " +
150    "--show-annotation android.annotation.SystemApi\\(" +
151        "client=android.annotation.SystemApi.Client.PRIVILEGED_APPS" +
152    "\\) "
153
154module_libs = " " +
155    " --show-annotation android.annotation.SystemApi\\(" +
156        "client=android.annotation.SystemApi.Client.MODULE_LIBRARIES" +
157    "\\) "
158
159droidstubs {
160    name: "system-api-stubs-docs",
161    defaults: ["metalava-full-api-stubs-default"],
162    removed_dex_api_filename: "system-removed-dex.txt",
163    arg_files: [
164        "core/res/AndroidManifest.xml",
165    ],
166    args: metalava_framework_docs_args + priv_apps,
167    check_api: {
168        current: {
169            api_file: "api/system-current.txt",
170            removed_api_file: "api/system-removed.txt",
171        },
172        last_released: {
173            api_file: ":android.api.system.latest",
174            removed_api_file: ":removed.api.system.latest",
175            baseline_file: ":system-api-incompatibilities-with-last-released"
176        },
177        api_lint: {
178            enabled: true,
179            new_since: ":android.api.system.latest",
180            baseline_file: "api/system-lint-baseline.txt",
181        },
182    },
183    dist: {
184        targets: ["sdk", "win_sdk"],
185        dir: "apistubs/android/system/api",
186        dest: "android.txt",
187    },
188    jdiff_enabled: true,
189}
190
191droidstubs {
192    name: "system-api-stubs-docs-non-updatable",
193    defaults: ["metalava-non-updatable-api-stubs-default"],
194    arg_files: ["core/res/AndroidManifest.xml"],
195    args: metalava_framework_docs_args + priv_apps,
196    check_api: {
197        current: {
198            api_file: "non-updatable-api/system-current.txt",
199            removed_api_file: "non-updatable-api/system-removed.txt",
200        },
201        api_lint: {
202            enabled: true,
203            new_since: ":android-non-updatable.api.system.latest",
204            baseline_file: "non-updatable-api/system-lint-baseline.txt",
205        },
206    },
207}
208
209droidstubs {
210    name: "test-api-stubs-docs",
211    defaults: ["metalava-full-api-stubs-default"],
212    arg_files: [
213        "core/res/AndroidManifest.xml",
214    ],
215    args: metalava_framework_docs_args + " --show-annotation android.annotation.TestApi",
216    check_api: {
217        current: {
218            api_file: "api/test-current.txt",
219            removed_api_file: "api/test-removed.txt",
220        },
221        api_lint: {
222            enabled: true,
223            baseline_file: "api/test-lint-baseline.txt",
224        },
225    },
226    dist: {
227        targets: ["sdk", "win_sdk"],
228        dir: "apistubs/android/test/api",
229        dest: "android.txt",
230    },
231}
232
233/////////////////////////////////////////////////////////////////////
234// Following droidstubs modules are for extra APIs for modules.
235// The framework currently have two more API surfaces for modules:
236// @SystemApi(client=MODULE_APPS) and @SystemApi(client=MODULE_LIBRARIES)
237/////////////////////////////////////////////////////////////////////
238
239// TODO(b/146727827) remove the *-api module when we can teach metalava
240// about the relationship among the API surfaces. Currently, these modules are only to generate
241// the API signature files and ensure that the APIs evolve in a backwards compatible manner.
242// They however are NOT used for building the API stub.
243
244droidstubs {
245    name: "module-lib-api",
246    defaults: ["metalava-full-api-stubs-default"],
247    arg_files: ["core/res/AndroidManifest.xml"],
248    args: metalava_framework_docs_args + module_libs,
249    check_api: {
250        current: {
251            api_file: "api/module-lib-current.txt",
252            removed_api_file: "api/module-lib-removed.txt",
253        },
254        last_released: {
255            api_file: ":android.api.module-lib.latest",
256            removed_api_file: ":removed.api.module-lib.latest",
257            baseline_file: ":module-lib-api-incompatibilities-with-last-released"
258        },
259        api_lint: {
260            enabled: true,
261            new_since: ":android.api.module-lib.latest",
262            baseline_file: "api/module-lib-lint-baseline.txt",
263        },
264    },
265    dist: {
266        targets: ["sdk", "win_sdk"],
267        dir: "apistubs/android/module-lib/api",
268        dest: "android.txt",
269    },
270}
271
272droidstubs {
273    name: "module-lib-api-stubs-docs-non-updatable",
274    defaults: ["metalava-non-updatable-api-stubs-default"],
275    arg_files: ["core/res/AndroidManifest.xml"],
276    args: metalava_framework_docs_args + module_libs,
277    check_api: {
278        current: {
279            api_file: "non-updatable-api/module-lib-current.txt",
280            removed_api_file: "non-updatable-api/module-lib-removed.txt",
281        },
282        api_lint: {
283            enabled: true,
284            new_since: ":android-non-updatable.api.module-lib.latest",
285        },
286    },
287}
288
289// The following droidstub module generates source files for the API stub library for
290// modules. Note that it not only includes its own APIs but also other APIs that have
291// narrower scope (all @SystemApis, not just the ones with 'client=MODULE_LIBRARIES').
292
293droidstubs {
294    name: "module-lib-api-stubs-docs",
295    defaults: ["metalava-non-updatable-api-stubs-default"],
296    arg_files: ["core/res/AndroidManifest.xml"],
297    args: metalava_framework_docs_args + priv_apps + module_libs,
298}
299
300/////////////////////////////////////////////////////////////////////
301// android_*_stubs_current modules are the stubs libraries compiled
302// from *-api-stubs-docs
303/////////////////////////////////////////////////////////////////////
304
305java_defaults {
306    name: "android_defaults_stubs_current",
307    libs: [ "stub-annotations" ],
308    errorprone: {
309        javacflags: [
310            "-XepDisableAllChecks",
311        ],
312    },
313    java_resources: [":notices-for-framework-stubs"],
314    sdk_version: "none",
315    system_modules: "none",
316    java_version: "1.8",
317    compile_dex: true,
318}
319
320java_library_static {
321    name: "android_monolith_stubs_current",
322    srcs: [ ":api-stubs-docs" ],
323    static_libs: [ "private-stub-annotations-jar" ],
324    defaults: ["android_defaults_stubs_current"],
325}
326
327java_library_static {
328    name: "android_merged_stubs_current",
329    srcs: [ ":api-stubs-docs-non-updatable" ],
330    static_libs: [
331        "conscrypt.module.public.api.stubs",
332        "framework-media.stubs",
333        "framework-mediaprovider.stubs",
334        "framework-permission.stubs",
335        "framework-sdkextensions.stubs",
336        "framework-statsd.stubs",
337        "framework-tethering.stubs",
338        "framework-wifi.stubs",
339        "private-stub-annotations-jar",
340    ],
341    defaults: ["android_defaults_stubs_current"],
342}
343
344java_library_static {
345    name: "android_stubs_current",
346    static_libs: ["android_merged_stubs_current"],
347    defaults: ["android_defaults_stubs_current"],
348}
349
350java_library_static {
351    name: "android_system_monolith_stubs_current",
352    srcs: [ ":system-api-stubs-docs" ],
353    static_libs: [ "private-stub-annotations-jar" ],
354    defaults: ["android_defaults_stubs_current"],
355}
356
357java_library_static {
358    name: "android_system_merged_stubs_current",
359    srcs: [ ":system-api-stubs-docs-non-updatable" ],
360    static_libs: [
361        "conscrypt.module.public.api.stubs",
362        "framework-media.stubs.system",
363        "framework-mediaprovider.stubs.system",
364        "framework-permission.stubs.system",
365        "framework-sdkextensions.stubs.system",
366        "framework-statsd.stubs.system",
367        "framework-tethering.stubs.system",
368        "framework-wifi.stubs.system",
369        "private-stub-annotations-jar",
370    ],
371    defaults: ["android_defaults_stubs_current"],
372}
373
374java_library_static {
375    name: "android_system_stubs_current",
376    static_libs: ["android_system_merged_stubs_current"],
377    defaults: ["android_defaults_stubs_current"],
378}
379
380java_library_static {
381    name: "android_test_stubs_current",
382    srcs: [ ":test-api-stubs-docs" ],
383    static_libs: [ "private-stub-annotations-jar" ],
384    defaults: ["android_defaults_stubs_current"],
385}
386
387java_library_static {
388    name: "android_module_lib_stubs_current",
389    srcs: [ ":module-lib-api-stubs-docs" ],
390    defaults: ["android_defaults_stubs_current"],
391    libs: ["sdk_system_29_android"],
392}
393
394java_library_static {
395    name: "android_non_updatable_stubs_current",
396    srcs: [":api-stubs-docs-non-updatable"],
397    defaults: ["android_defaults_stubs_current"],
398    libs: ["sdk_system_29_android"],
399}
400
401java_library_static {
402    name: "android_system_non_updatable_stubs_current",
403    srcs: [":system-api-stubs-docs-non-updatable"],
404    defaults: ["android_defaults_stubs_current"],
405    libs: ["sdk_system_29_android"],
406}
407
408/////////////////////////////////////////////////////////////////////
409// hwbinder.stubs provides APIs required for building HIDL Java
410// libraries.
411/////////////////////////////////////////////////////////////////////
412
413droidstubs {
414    name: "hwbinder-stubs-docs",
415    srcs: [
416        "core/java/android/os/HidlSupport.java",
417        "core/java/android/annotation/IntDef.java",
418        "core/java/android/annotation/IntRange.java",
419        "core/java/android/annotation/NonNull.java",
420        "core/java/android/annotation/SystemApi.java",
421        "core/java/android/os/HidlMemory.java",
422        "core/java/android/os/HwBinder.java",
423        "core/java/android/os/HwBlob.java",
424        "core/java/android/os/HwParcel.java",
425        "core/java/android/os/IHwBinder.java",
426        "core/java/android/os/IHwInterface.java",
427        "core/java/android/os/DeadObjectException.java",
428        "core/java/android/os/DeadSystemException.java",
429        "core/java/android/os/NativeHandle.java",
430        "core/java/android/os/RemoteException.java",
431        "core/java/android/util/AndroidException.java",
432    ],
433    installable: false,
434    sdk_version: "core_platform",
435    annotations_enabled: true,
436    previous_api: ":android.api.public.latest",
437    merge_annotations_dirs: [
438        "metalava-manual",
439    ],
440    args: priv_apps,
441}
442
443java_library_static {
444    name: "hwbinder.stubs",
445    sdk_version: "core_current",
446    srcs: [
447        ":hwbinder-stubs-docs",
448    ],
449}
450
451/////////////////////////////////////////////////////////////////////
452// api/*-current.txt files for use by modules in other directories
453// like the CTS test
454/////////////////////////////////////////////////////////////////////
455
456filegroup {
457    name: "frameworks-base-api-current.txt",
458    srcs: [
459        "api/current.txt",
460    ],
461}
462
463filegroup {
464    name: "frameworks-base-api-system-current.txt",
465    srcs: [
466        "api/system-current.txt",
467    ],
468}
469
470filegroup {
471    name: "frameworks-base-api-system-removed.txt",
472    srcs: [
473        "api/system-removed.txt",
474    ],
475}
476