Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 7fb4b183 authored by Jiyong Park's avatar Jiyong Park
Browse files

Separate modules for API docs and API stubs 

frameworks/base/Android.bp became too big. Modularize it into multiple
files for better readability and extensibility.

droidstubs and java_library modules for API stub libraries are moved to
StubLibraries.bp.

droidstubs and droiddoc modules for API documents are moved to
ApiDocs.bp

Also, added some documentation to explain the roles of the many modules
and how they are related with each other.

Bug: N/A
Test: m

Exempt-From-Owner-Approval: cherry-pick from internal

Merged-In: I285e8c82078d5bd3ed85b0343db2f6375ce7ffb7
(cherry picked from commit 0d7e86d0)
Change-Id: I285e8c82078d5bd3ed85b0343db2f6375ce7ffb7
parent 5640e1d8

Android.bp

+17 −647
Original line number Diff line number Diff line
@@ -936,653 +936,6 @@ python_binary_host { 
    ],

}



// Make the api/current.txt file available for use by modules in other

// directories.

filegroup {

    name: "frameworks-base-api-current.txt",

    srcs: [

        "api/current.txt",

    ],

}



// Make the api/system-current.txt file available for use by modules in other

// directories.

filegroup {

    name: "frameworks-base-api-system-current.txt",

    srcs: [

        "api/system-current.txt",

    ],

}



// Make the api/system-removed.txt file available for use by modules in other

// directories.

filegroup {

    name: "frameworks-base-api-system-removed.txt",

    srcs: [

        "api/system-removed.txt",

    ],

}



framework_docs_only_args = " -android -manifest $(location core/res/AndroidManifest.xml) " +

    "-werror -lerror -hide 111 -hide 113 -hide 125 -hide 126 -hide 127 -hide 128 " +

    "-overview $(location core/java/overview.html) " +

    // Federate Support Library references against local API file.

    "-federate SupportLib https://developer.android.com " +

    "-federationapi SupportLib $(location :current-support-api) " +

    // Federate Support Library references against local API file.

    "-federate AndroidX https://developer.android.com " +

    "-federationapi AndroidX $(location :current-androidx-api) "



framework_docs_only_libs = [

    "voip-common",

    "android.test.mock",

    "android-support-annotations",

    "android-support-compat",

    "android-support-core-ui",

    "android-support-core-utils",

    "android-support-customtabs",

    "android-support-design",

    "android-support-dynamic-animation",

    "android-support-exifinterface",

    "android-support-fragment",

    "android-support-media-compat",

    "android-support-percent",

    "android-support-recommendation",

    "android-support-transition",

    "android-support-tv-provider",

    "android-support-v7-cardview",

    "android-support-v7-gridlayout",

    "android-support-v7-mediarouter",

    "android-support-v7-palette",

    "android-support-v7-preference",

    "android-support-v13",

    "android-support-v14-preference",

    "android-support-v17-leanback",

    "android-support-v17-preference-leanback",

    "android-support-wear",

    "android-support-vectordrawable",

    "android-support-animatedvectordrawable",

    "android-support-v7-appcompat",

    "android-support-v7-recyclerview",

    "android-support-emoji",

    "android-support-emoji-appcompat",

    "android-support-emoji-bundled",

    "android-support-v8-renderscript",

    "android-support-multidex",

    "android-support-multidex-instrumentation",

]



metalava_framework_docs_args = "--manifest $(location core/res/AndroidManifest.xml) " +

    "--ignore-classes-on-classpath " +

    "--hide-package com.android.server " +

    "--error UnhiddenSystemApi " +

    "--hide RequiresPermission " +

    "--hide CallbackInterface " +

    "--hide MissingPermission --hide BroadcastBehavior " +

    "--hide HiddenSuperclass --hide DeprecationMismatch --hide UnavailableSymbol " +

    "--hide SdkConstant --hide HiddenTypeParameter --hide Todo --hide Typo " +

    "--force-convert-to-warning-nullability-annotations +*:-android.*:+android.icu.*:-dalvik.*"



packages_to_document = [

    "android",

    "dalvik",

    "java",

    "javax",

    "junit",

    "org.apache.http",

    "org.json",

    "org.w3c.dom",

    "org.xml.sax",

    "org.xmlpull",

]



stubs_defaults {

    name: "framework-doc-stubs-default",

    srcs: [

        ":framework-mime-sources",

        ":framework-non-updatable-sources",

        ":framework-updatable-sources",

        "core/java/**/*.logtags",

        "test-base/src/**/*.java",

        ":opt-telephony-srcs",

        ":opt-net-voip-srcs",

        ":core-current-stubs-source",

        ":core_public_api_files",

        "test-mock/src/**/*.java",

        "test-runner/src/**/*.java",

    ],

    libs: framework_docs_only_libs,

    create_doc_stubs: true,

    annotations_enabled: true,

    api_levels_annotations_enabled: true,

    api_levels_annotations_dirs: [

        "sdk-dir",

        "api-versions-jars-dir",

    ],

    previous_api: ":last-released-public-api",

    merge_annotations_dirs: [

        "metalava-manual",

    ],

}



doc_defaults {

    name: "framework-docs-default",

    libs: framework_docs_only_libs +

        ["stub-annotations"],

    html_dirs: [

        "docs/html",

    ],

    knowntags: [

        "docs/knowntags.txt",

        ":known-oj-tags",

    ],

    custom_template: "droiddoc-templates-sdk",

    resourcesdir: "docs/html/reference/images/",

    resourcesoutdir: "reference/android/images/",

    hdf: [

        "dac true",

        "sdk.codename O",

        "sdk.preview.version 1",

        "sdk.version 7.0",

        "sdk.rel.id 1",

        "sdk.preview 0",

    ],

    arg_files: [

        "core/res/AndroidManifest.xml",

        "core/java/overview.html",

        ":current-support-api",

        ":current-androidx-api",

    ],

    create_stubs: false,

}



doc_defaults {

    name: "framework-dokka-docs-default",

    create_stubs: false,

}



stubs_defaults {

    name: "metalava-api-stubs-default",

    srcs: [

        ":framework-non-updatable-sources",

        ":framework-updatable-sources",

        "core/java/**/*.logtags",

        ":opt-telephony-srcs",

        ":opt-net-voip-srcs",

        ":core-current-stubs-source",

        ":core_public_api_files",

        ":ike-api-srcs",

    ],

    libs: ["framework-internal-utils"],

    installable: false,

    annotations_enabled: true,

    previous_api: ":last-released-public-api",

    merge_annotations_dirs: [

        "metalava-manual",

    ],

    api_levels_annotations_enabled: true,

    api_levels_annotations_dirs: [

        "sdk-dir",

        "api-versions-jars-dir",

    ],

    sdk_version: "core_platform",

    filter_packages: packages_to_document,

}



droidstubs {

    name: "framework-doc-stubs",

    defaults: ["framework-doc-stubs-default"],

    arg_files: [

        "core/res/AndroidManifest.xml",

    ],

    args: metalava_framework_docs_args,

    write_sdk_values: true,

}



droidstubs {

    name: "framework-doc-system-stubs",

    defaults: ["framework-doc-stubs-default"],

    arg_files: [

        "core/res/AndroidManifest.xml",

    ],

    args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\) ",

    write_sdk_values: true,

}



droiddoc {

    name: "doc-comment-check-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    args: framework_docs_only_args + " -referenceonly -parsecomments",

    installable: false,

}



droiddoc {

    name: "offline-sdk-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    hdf: [

        "android.whichdoc offline",

    ],

    proofread_file: "offline-sdk-docs-proofrerad.txt",

    args: framework_docs_only_args + " -offlinemode -title \"Android SDK\"",

    static_doc_index_redirect: "docs/docs-preview-index.html",

}



droiddoc {

    // Please sync with android-api-council@ before making any changes for the name property below.

    // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically.

    // See b/116221385 for reference.

    name: "offline-sdk-referenceonly-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    hdf: [

        "android.whichdoc offline",

    ],

    proofread_file: "offline-sdk-referenceonly-docs-proofrerad.txt",

    args: framework_docs_only_args + " -offlinemode -title \"Android SDK\" -referenceonly",

    static_doc_index_redirect: "docs/docs-documentation-redirect.html",

    static_doc_properties: "docs/source.properties",

}



droiddoc {

    // Please sync with android-api-council@ before making any changes for the name property below.

    // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically.

    // See b/116221385 for reference.

    name: "offline-system-sdk-referenceonly-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-system-stubs",

    ],

    hdf: [

        "android.whichdoc offline",

    ],

    proofread_file: "offline-system-sdk-referenceonly-docs-proofrerad.txt",

    args: framework_docs_only_args + " -hide 101 -hide 104 -hide 108" +

    " -offlinemode -title \"Android System SDK\" -referenceonly",

    static_doc_index_redirect: "docs/docs-documentation-redirect.html",

    static_doc_properties: "docs/source.properties",

}



droiddoc {

    name: "online-sdk-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    hdf: [

        "android.whichdoc online",

        "android.hasSamples true",

    ],

    proofread_file: "online-sdk-docs-proofrerad.txt",

    args: framework_docs_only_args +

        " -toroot / -samplegroup Admin " +

        " -samplegroup Background " +

        " -samplegroup Connectivity " +

        " -samplegroup Content " +

        " -samplegroup Input " +

        " -samplegroup Media " +

        " -samplegroup Notification " +

        " -samplegroup RenderScript " +

        " -samplegroup Security " +

        " -samplegroup Sensors " +

        " -samplegroup System " +

        " -samplegroup Testing " +

        " -samplegroup UI " +

        " -samplegroup Views " +

        " -samplegroup Wearable -samplesdir development/samples/browseable ",

}



droiddoc {

    name: "online-system-api-sdk-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-system-stubs",

    ],

    hdf: [

        "android.whichdoc online",

        "android.hasSamples true",

    ],

    proofread_file: "online-system-api-sdk-docs-proofrerad.txt",

    args: framework_docs_only_args +

        " -referenceonly " +

        " -title \"Android SDK - Including system APIs.\" " +

        " -hide 101 " +

        " -hide 104 " +

        " -hide 108 " +

        " -toroot / -samplegroup Admin " +

        " -samplegroup Background " +

        " -samplegroup Connectivity " +

        " -samplegroup Content " +

        " -samplegroup Input " +

        " -samplegroup Media " +

        " -samplegroup Notification " +

        " -samplegroup RenderScript " +

        " -samplegroup Security " +

        " -samplegroup Sensors " +

        " -samplegroup System " +

        " -samplegroup Testing " +

        " -samplegroup UI " +

        " -samplegroup Views " +

        " -samplegroup Wearable -samplesdir development/samples/browseable ",

    installable: false,

}



droiddoc {

    name: "ds-docs-java",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    hdf: [

        "android.whichdoc online",

        "android.hasSamples true",

    ],

    proofread_file: "ds-docs-proofrerad.txt",

    args: framework_docs_only_args +

        " -toroot / -yamlV2 -metalavaApiSince -samplegroup Admin " +

        " -samplegroup Background " +

        " -samplegroup Connectivity " +

        " -samplegroup Content " +

        " -samplegroup Input " +

        " -samplegroup Media " +

        " -samplegroup Notification " +

        " -samplegroup RenderScript " +

        " -samplegroup Security " +

        " -samplegroup Sensors " +

        " -samplegroup System " +

        " -samplegroup Testing " +

        " -samplegroup UI " +

        " -samplegroup Views " +

        " -samplegroup Wearable -devsite -samplesdir development/samples/browseable ",

}



droiddoc {

    name: "ds-docs-kt",

    defaults: ["framework-dokka-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    args: "-noJdkLink -links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list " +

    "-noStdlibLink",

    proofread_file: "ds-dokka-proofread.txt",

    dokka_enabled: true,

}



java_genrule {

    name: "ds-docs",

    tools: [

        "zip2zip",

        "merge_zips",

    ],

    srcs: [

        ":ds-docs-java{.docs.zip}",

        ":ds-docs-kt{.docs.zip}",

    ],

    out: ["ds-docs.zip"],

    dist: {

        targets: ["docs"],

    },

    cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " +

         "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip",

}



java_genrule {

    name: "ds-docs-switched",

    tools: [

        "switcher4",

        "soong_zip",

    ],

    srcs: [

        ":ds-docs-java{.docs.zip}",

        ":ds-docs-kt{.docs.zip}",

    ],

    out: ["ds-docs-switched.zip"],

    dist: {

        targets: ["docs"],

    },

    cmd: "unzip $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " +

         "unzip $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " +

         "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " +

         "(cd $(genDir)/en/reference && $$SWITCHER --work platform) && " +

         "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)",

}





droiddoc {

    name: "ds-static-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    hdf: [

        "android.whichdoc online",

    ],

    proofread_file: "ds-static-docs-proofrerad.txt",

    args: framework_docs_only_args +

        " -staticonly " +

        " -toroot / " +

        " -devsite " +

        " -ignoreJdLinks ",

}



droiddoc {

    name: "ds-ref-navtree-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    hdf: [

        "android.whichdoc online",

    ],

    proofread_file: "ds-ref-navtree-docs-proofrerad.txt",

    args: framework_docs_only_args +

        " -toroot / " +

        " -atLinksNavtree " +

        " -navtreeonly ",

}



droiddoc {

    name: "online-sdk-dev-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    hdf: [

        "android.whichdoc online",

        "android.hasSamples true",

    ],

    proofread_file: "online-sdk-dev-docs-proofrerad.txt",

    args: framework_docs_only_args +

        " -toroot / -samplegroup Admin " +

        " -samplegroup Background " +

        " -samplegroup Connectivity " +

        " -samplegroup Content " +

        " -samplegroup Input " +

        " -samplegroup Media " +

        " -samplegroup Notification " +

        " -samplegroup RenderScript " +

        " -samplegroup Security " +

        " -samplegroup Sensors " +

        " -samplegroup System " +

        " -samplegroup Testing " +

        " -samplegroup UI " +

        " -samplegroup Views " +

        " -samplegroup Wearable -samplesdir development/samples/browseable ",

}



droiddoc {

    name: "hidden-docs",

    defaults: ["framework-docs-default"],

    srcs: [

        ":framework-doc-stubs",

    ],

    proofread_file: "hidden-docs-proofrerad.txt",

    args: framework_docs_only_args +

        " -referenceonly " +

        " -title \"Android SDK - Including hidden APIs.\"",

}



droidstubs {

    name: "hwbinder-stubs-docs",

    srcs: [

        "core/java/android/os/HidlSupport.java",

        "core/java/android/annotation/IntDef.java",

        "core/java/android/annotation/IntRange.java",

        "core/java/android/annotation/NonNull.java",

        "core/java/android/annotation/SystemApi.java",

        "core/java/android/os/HidlMemory.java",

        "core/java/android/os/HwBinder.java",

        "core/java/android/os/HwBlob.java",

        "core/java/android/os/HwParcel.java",

        "core/java/android/os/IHwBinder.java",

        "core/java/android/os/IHwInterface.java",

        "core/java/android/os/DeadObjectException.java",

        "core/java/android/os/DeadSystemException.java",

        "core/java/android/os/NativeHandle.java",

        "core/java/android/os/RemoteException.java",

        "core/java/android/util/AndroidException.java",

    ],

    installable: false,

    sdk_version: "core_platform",

    annotations_enabled: true,

    previous_api: ":last-released-public-api",

    merge_annotations_dirs: [

        "metalava-manual",

    ],

    args: " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\)",

}



java_library_static {

    name: "hwbinder.stubs",

    sdk_version: "core_current",

    srcs: [

        ":hwbinder-stubs-docs",

    ],

}



droidstubs {

    name: "hiddenapi-lists-docs",

    defaults: ["metalava-api-stubs-default"],

    arg_files: [

        "core/res/AndroidManifest.xml",

    ],

    dex_api_filename: "public-dex.txt",

    private_dex_api_filename: "private-dex.txt",

    removed_dex_api_filename: "removed-dex.txt",

    args: metalava_framework_docs_args +

        " --show-unannotated " +

        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\) " +

        " --show-annotation android.annotation.TestApi ",

}



droidstubs {

    name: "hiddenapi-mappings",

    defaults: ["metalava-api-stubs-default"],

    srcs: [

        ":opt-telephony-common-srcs",

    ],



    arg_files: [

        "core/res/AndroidManifest.xml",

    ],

    dex_mapping_filename: "dex-mapping.txt",

    args: metalava_framework_docs_args +

        " --hide ReferencesHidden " +

        " --hide UnhiddenSystemApi " +

        " --show-unannotated " +

        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\) " +

        " --show-annotation android.annotation.TestApi ",

}



droidstubs {

    name: "api-stubs-docs",

    defaults: ["metalava-api-stubs-default"],

    api_filename: "public_api.txt",

    private_api_filename: "private.txt",

    removed_api_filename: "removed.txt",

    arg_files: [

        "core/res/AndroidManifest.xml",

    ],

    args: metalava_framework_docs_args,

    check_api: {

        current: {

            api_file: "api/current.txt",

            removed_api_file: "api/removed.txt",

        },

        last_released: {

            api_file: ":last-released-public-api",

            removed_api_file: "api/removed.txt",

            baseline_file: ":public-api-incompatibilities-with-last-released",

        },

        api_lint: {

            enabled: true,

            new_since: ":last-released-public-api",

            baseline_file: "api/lint-baseline.txt",

        },

    },

    jdiff_enabled: true,

}



droidstubs {

    name: "system-api-stubs-docs",

    defaults: ["metalava-api-stubs-default"],

    api_tag_name: "SYSTEM",

    api_filename: "system-api.txt",

    private_api_filename: "system-private.txt",

    private_dex_api_filename: "system-private-dex.txt",

    removed_api_filename: "system-removed.txt",

    arg_files: [

        "core/res/AndroidManifest.xml",

    ],

    args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\)",

    check_api: {

        current: {

            api_file: "api/system-current.txt",

            removed_api_file: "api/system-removed.txt",

        },

        last_released: {

            api_file: ":last-released-system-api",

            removed_api_file: "api/system-removed.txt",

            baseline_file: ":system-api-incompatibilities-with-last-released"

        },

        api_lint: {

            enabled: true,

            new_since: ":last-released-system-api",

            baseline_file: "api/system-lint-baseline.txt",

        },

    },

    jdiff_enabled: true,

}



droidstubs {

    name: "test-api-stubs-docs",

    defaults: ["metalava-api-stubs-default"],

    api_tag_name: "TEST",

    api_filename: "test-api.txt",

    removed_api_filename: "test-removed.txt",

    arg_files: [

        "core/res/AndroidManifest.xml",

    ],

    args: metalava_framework_docs_args + " --show-annotation android.annotation.TestApi",

    check_api: {

        current: {

            api_file: "api/test-current.txt",

            removed_api_file: "api/test-removed.txt",

        },

        api_lint: {

            enabled: true,

            baseline_file: "api/test-lint-baseline.txt",

        },

    },

}



filegroup {

    name: "framework-annotation-nonnull-srcs",

    srcs: [
@@ -1663,3 +1016,20 @@ filegroup { 
        "core/java/com/android/internal/util/UserIcons.java",

    ],

}



// TODO(b/145644363): move this to under StubLibraries.bp or ApiDocs.bp

metalava_framework_docs_args = "--manifest $(location core/res/AndroidManifest.xml) " +

    "--ignore-classes-on-classpath " +

    "--hide-package com.android.server " +

    "--error UnhiddenSystemApi " +

    "--hide RequiresPermission " +

    "--hide CallbackInterface " +

    "--hide MissingPermission --hide BroadcastBehavior " +

    "--hide HiddenSuperclass --hide DeprecationMismatch --hide UnavailableSymbol " +

    "--hide SdkConstant --hide HiddenTypeParameter --hide Todo --hide Typo " +

    "--force-convert-to-warning-nullability-annotations +*:-android.*:+android.icu.*:-dalvik.*"



build = [

    "StubLibraries.bp",

    "ApiDocs.bp",

]

ApiDocs.bp

0 → 100644
+436 −0

File added.

Preview size limit exceeded, changes collapsed.

StubLibraries.bp

0 → 100644
+340 −0

File added.

Preview size limit exceeded, changes collapsed.