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 API docs are generated: 16// 17// raw source files --(metalava)--> stub source files --(doclava)--> API doc 18// 19// The metalava conversion is done by droidstub modules framework-doc-*-stubs. 20// The API doc generation is done by the various droiddoc modules each of which 21// is for different format. 22 23// These defaults enable doc-stub generation, api lint database generation and sdk value generation. 24stubs_defaults { 25 name: "android-non-updatable-doc-stubs-defaults", 26 defaults: ["android-non-updatable-stubs-defaults"], 27 srcs: [ 28 // No longer part of the stubs, but are included in the docs. 29 ":android-test-base-sources", 30 ":android-test-mock-sources", 31 ":android-test-runner-sources", 32 ], 33 flags: [ 34 // These errors are suppressed in the doc stubs as it isn't easy to suppress them. 35 // They remain unsuppressed/active in the "main" stubs build (the jar stubs). 36 // These can be removed when either a) all the issues have been fixed or 37 // b) these reporting of these issues is gated behind api lint being enabled in metalava. 38 "--hide BroadcastBehavior", 39 "--hide DeprecationMismatch", 40 "--hide MissingPermission", 41 "--hide RequiresPermission", 42 "--hide SdkConstant", 43 "--hide Todo", 44 ], 45 create_doc_stubs: true, 46 write_sdk_values: true, 47} 48 49// Defaults module for doc-stubs targets that use module source code as input. 50stubs_defaults { 51 name: "framework-doc-stubs-sources-default", 52 defaults: ["android-non-updatable-doc-stubs-defaults"], 53 srcs: [ 54 ":art.module.public.api{.public.stubs.source}", 55 ":conscrypt.module.public.api{.public.stubs.source}", 56 ":i18n.module.public.api{.public.stubs.source}", 57 58 ":framework-adservices-sources", 59 ":framework-appsearch-sources", 60 ":framework-connectivity-sources", 61 ":framework-bluetooth-sources", 62 ":framework-connectivity-tiramisu-updatable-sources", 63 ":framework-graphics-srcs", 64 ":framework-healthfitness-sources", 65 ":framework-mediaprovider-sources", 66 ":framework-nearby-sources", 67 ":framework-nfc-updatable-sources", 68 ":framework-ondevicepersonalization-sources", 69 ":framework-permission-sources", 70 ":framework-permission-s-sources", 71 ":framework-profiling-sources", 72 ":framework-scheduling-sources", 73 ":framework-sdkextensions-sources", 74 ":framework-statsd-sources", 75 ":framework-sdksandbox-sources", 76 ":framework-tethering-srcs", 77 ":framework-uwb-updatable-sources", 78 ":framework-wifi-updatable-sources", 79 ":ike-srcs", 80 ":updatable-media-srcs", 81 ], 82} 83 84droidstubs { 85 name: "android-non-updatable-doc-stubs", 86 defaults: [ 87 "android-non-updatable-doc-stubs-defaults", 88 "module-classpath-stubs-defaults", 89 ], 90} 91 92droidstubs { 93 name: "android-non-updatable-doc-stubs-system", 94 defaults: [ 95 "android-non-updatable-doc-stubs-defaults", 96 "module-classpath-stubs-defaults", 97 ], 98 flags: ["--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)"], 99} 100 101droidstubs { 102 name: "android-non-updatable-doc-stubs-module-lib", 103 defaults: [ 104 "android-non-updatable-doc-stubs-defaults", 105 "module-classpath-stubs-defaults", 106 ], 107 flags: [ 108 "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)", 109 "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\)", 110 ], 111 generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs. 112 write_sdk_values: false, 113} 114 115droidstubs { 116 name: "android-non-updatable-doc-stubs-system-server", 117 defaults: [ 118 "android-non-updatable-doc-stubs-defaults", 119 "module-classpath-stubs-defaults", 120 ], 121 flags: [ 122 "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)", 123 "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\)", 124 "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.SYSTEM_SERVER\\)", 125 ], 126 generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs. 127 write_sdk_values: false, 128} 129 130droidstubs { 131 name: "framework-doc-stubs", 132 defaults: ["android-non-updatable-doc-stubs-defaults"], 133 flags: [ 134 // Ignore any compatibility errors, see check_api.last_released below for more information. 135 "--hide-category Compatibility", 136 ], 137 srcs: [":all-modules-public-stubs-source-exportable"], 138 api_levels_module: "api_versions_public", 139 aidl: { 140 include_dirs: [ 141 "packages/modules/Connectivity/framework/aidl-export", 142 "packages/modules/Media/apex/aidl/stable", 143 ], 144 }, 145 146 // Pass the previously released API to support reverting flagged APIs. Without this, reverting 147 // a flagged API will cause it to be removed, even if it had previously been released. This 148 // has the side effect of causing compatibility issues to be reported but they are already 149 // checked elsewhere so they will be ignored, see `--hide-category Compatibility` above. 150 check_api: { 151 last_released: { 152 api_file: ":android.api.combined.public.latest", 153 removed_api_file: ":android-removed.api.combined.public.latest", 154 }, 155 }, 156} 157 158droidstubs { 159 name: "framework-doc-system-stubs", 160 defaults: ["framework-doc-stubs-sources-default"], 161 flags: [ 162 "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)", 163 // Ignore any compatibility errors, see check_api.last_released below for more information. 164 "--hide-category Compatibility", 165 ], 166 api_levels_module: "api_versions_system", 167 168 // Pass the previously released API to support reverting flagged APIs. Without this, reverting 169 // a flagged API will cause it to be removed, even if it had previously been released. This 170 // has the side effect of causing compatibility issues to be reported but they are already 171 // checked elsewhere so they will be ignored, see `--hide-category Compatibility` above. 172 check_api: { 173 last_released: { 174 api_file: ":android.api.combined.system.latest", 175 removed_api_file: ":android-removed.api.combined.system.latest", 176 }, 177 }, 178} 179 180///////////////////////////////////////////////////////////////////// 181// API docs are created from the generated stub source files 182// using droiddoc 183///////////////////////////////////////////////////////////////////// 184 185doc_defaults { 186 name: "framework-docs-default", 187 sdk_version: "none", 188 system_modules: "none", 189 libs: [ 190 "stub-annotations", 191 "unsupportedappusage", 192 ], 193 html_dirs: [ 194 "docs/html", 195 ], 196 knowntags: [ 197 "docs/knowntags.txt", 198 ":art.module.public.api{.doctags}", 199 ], 200 custom_template: "droiddoc-templates-sdk", 201 resourcesdir: "docs/html/reference/images/", 202 resourcesoutdir: "reference/android/images/", 203 lint_baseline: "javadoc-lint-baseline", 204 flags: [ 205 "-android", 206 "-manifest $(location :frameworks-base-core-AndroidManifest.xml)", 207 "-metalavaApiSince", 208 "-werror", 209 "-lerror", 210 "-overview $(location :frameworks-base-java-overview)", 211 // Federate Support Library references against local API file. 212 "-federate SupportLib https://developer.android.com", 213 "-federationapi SupportLib $(location :current-support-api)", 214 // Federate Support Library references against local API file. 215 "-federate AndroidX https://developer.android.com", 216 "-federationapi AndroidX $(location :current-androidx-api)", 217 // doclava contains checks for a few issues that are have been migrated to metalava. 218 // disable them in doclava, to avoid mistriggering or double triggering. 219 "-hide 101", // TODO: turn Lint 101 back into an error again 220 "-hide 111", // HIDDEN_SUPERCLASS 221 "-hide 113", // DEPRECATION_MISMATCH 222 "-hide 125", // REQUIRES_PERMISSION 223 "-hide 126", // BROADCAST_BEHAVIOR 224 "-hide 127", // SDK_CONSTANT 225 "-hide 128", // TODO 226 ], 227 hdf: [ 228 "dac true", 229 "sdk.codename O", 230 "sdk.preview.version 1", 231 "sdk.version 7.0", 232 "sdk.rel.id 1", 233 "sdk.preview 0", 234 ], 235 arg_files: [ 236 ":frameworks-base-core-AndroidManifest.xml", 237 ":frameworks-base-java-overview", 238 ":current-support-api", 239 ":current-androidx-api", 240 ], 241 // TODO(b/169090544): remove below aidl includes. 242 aidl: { 243 include_dirs: [ 244 "frameworks/av/aidl", 245 "frameworks/base/media/aidl", 246 "frameworks/native/libs/permission/aidl", 247 ], 248 }, 249} 250 251droiddoc { 252 name: "offline-sdk-docs", 253 defaults: ["framework-docs-default"], 254 srcs: [ 255 ":framework-doc-stubs{.exportable}", 256 ], 257 hdf: [ 258 "android.whichdoc offline", 259 ], 260 compat_config: ":global-compat-config", 261 proofread_file: "offline-sdk-docs-proofread.txt", 262 flags: [ 263 "-offlinemode", 264 "-title \"Android SDK\"", 265 ], 266 static_doc_index_redirect: "docs/docs-preview-index.html", 267} 268 269droiddoc { 270 // Please sync with android-api-council@ before making any changes for the name property below. 271 // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically. 272 // See b/116221385 for reference. 273 name: "offline-sdk-referenceonly-docs", 274 defaults: ["framework-docs-default"], 275 srcs: [ 276 ":framework-doc-stubs{.exportable}", 277 ], 278 hdf: [ 279 "android.whichdoc offline", 280 ], 281 proofread_file: "offline-sdk-referenceonly-docs-proofread.txt", 282 flags: [ 283 "-offlinemode", 284 "-title \"Android SDK\"", 285 "-referenceonly", 286 ], 287 static_doc_index_redirect: "docs/docs-documentation-redirect.html", 288 static_doc_properties: "docs/source.properties", 289} 290 291droiddoc { 292 // Please sync with android-api-council@ before making any changes for the name property below. 293 // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically. 294 // See b/116221385 for reference. 295 name: "offline-system-sdk-referenceonly-docs", 296 defaults: ["framework-docs-default"], 297 srcs: [ 298 ":framework-doc-system-stubs", 299 ], 300 hdf: [ 301 "android.whichdoc offline", 302 ], 303 proofread_file: "offline-system-sdk-referenceonly-docs-proofread.txt", 304 flags: [ 305 "-hide 101", 306 "-hide 104", 307 "-hide 108", 308 "-offlinemode", 309 "-title \"Android System SDK\"", 310 "-referenceonly", 311 ], 312 static_doc_index_redirect: "docs/docs-documentation-redirect.html", 313 static_doc_properties: "docs/source.properties", 314} 315 316droiddoc { 317 name: "ds-docs-java", 318 defaults: ["framework-docs-default"], 319 srcs: [ 320 ":framework-doc-stubs{.exportable}", 321 ], 322 hdf: [ 323 "android.whichdoc online", 324 "android.hasSamples true", 325 ], 326 proofread_file: "ds-docs-proofread.txt", 327 flags: [ 328 " -toroot /", 329 "-yamlV2", 330 "-samplegroup Admin", 331 "-samplegroup Background", 332 "-samplegroup Connectivity", 333 "-samplegroup Content", 334 "-samplegroup Input", 335 "-samplegroup Media", 336 "-samplegroup Notification", 337 "-samplegroup RenderScript", 338 "-samplegroup Security", 339 "-samplegroup Sensors", 340 "-samplegroup System", 341 "-samplegroup Testing", 342 "-samplegroup UI", 343 "-samplegroup Views", 344 "-samplegroup Wearable", 345 "-devsite", 346 "-samplesdir", 347 "development/samples/browseable", 348 ], 349} 350 351droiddoc { 352 name: "ds-docs-kt", 353 srcs: [ 354 ":framework-doc-stubs{.exportable}", 355 ], 356 flags: [ 357 "-noJdkLink", 358 "-links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list", 359 "-noStdlibLink", 360 ], 361 proofread_file: "ds-dokka-proofread.txt", 362 dokka_enabled: true, 363} 364 365java_genrule { 366 name: "ds-docs", 367 tools: [ 368 "zip2zip", 369 "merge_zips", 370 ], 371 srcs: [ 372 ":ds-docs-java{.docs.zip}", 373 ":ds-docs-kt{.docs.zip}", 374 ], 375 out: ["ds-docs.zip"], 376 dist: { 377 targets: ["docs"], 378 }, 379 cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " + 380 "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip", 381} 382 383java_genrule { 384 name: "ds-docs-switched", 385 tools: [ 386 "switcher4", 387 "soong_zip", 388 ], 389 srcs: [ 390 ":ds-docs-java{.docs.zip}", 391 ":ds-docs-kt{.docs.zip}", 392 ], 393 out: ["ds-docs-switched.zip"], 394 dist: { 395 targets: ["docs"], 396 }, 397 cmd: "unzip -q $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " + 398 "unzip -q $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " + 399 "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " + 400 "(cd $(genDir)/en/reference && $$SWITCHER --work platform) > /dev/null && " + 401 "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)", 402} 403 404droiddoc { 405 name: "ds-static-docs", 406 defaults: ["framework-docs-default"], 407 srcs: [ 408 ":framework-doc-stubs{.exportable}", 409 ], 410 hdf: [ 411 "android.whichdoc online", 412 ], 413 flags: [ 414 "-staticonly", 415 "-toroot /", 416 "-devsite", 417 "-ignoreJdLinks", 418 ], 419} 420 421droiddoc { 422 name: "ds-ref-navtree-docs", 423 defaults: ["framework-docs-default"], 424 srcs: [ 425 ":framework-doc-stubs{.exportable}", 426 ], 427 hdf: [ 428 "android.whichdoc online", 429 ], 430 flags: [ 431 "-toroot /", 432 "-atLinksNavtree", 433 "-navtreeonly", 434 ], 435} 436